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* GETTING STARTED * 
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This manual has been designed as your guidebook to learning 
FORTH. Before you begin chapter 2.0, you will need to find a 
computer which supports the FORTH language. As you read each 
chapter, you should try typing in each example at your terminal 
just as it appears in the text. In the text, the computer's 
response will be underlined. 


If you have purchased the FORTH language software from 
MicroMotion, you should now turn to appendix A to learn how to 
start up on your particular computer. 


1-1 FORTH-79 STANDARD 


The FORTH used in this manual conforms to the International 
FORTH-79 Standard (October 1980). References will also be made 
to the earlier Forth Interest Group (FIG) Model whenever it 
differs significantly from the FORTH-79 Standard. 


In addition to the FORTH word set described by the FORTH-79 
Standard, many other useful FORTH words are described in this 
manual. The definitions of these words are given in appendix 
B. These definitions must be included in your FORTH version 
before they can be used. If you are using MicroMotion FORTH, 
these definitions have already been added. If not, you should 
ask someone familiar with the FORTH system you will be using to 
compile these definitions for you. 


A complete and alphabetically ordered glossary of all the 
FORTH words used in this manual is given in appendix C. The 
required word set of FORTH-79 is given in appendix D. Complete 
word sets organized by function, such as stack manipulation 
words, arithmetic words, and so forth, are given in appendix E. 
The FORTH-79 published standard is available for $10 (as of 
November 1980) from the FORTH Interest Group (see below). 


1-2 ADDITIONAL RESOURCES 


Local junior colleges, colleges and universities often 
sponsor computer clubs. You might be able to find someone at 
these clubs with an active interest in FORTH. Since FORTH is 
often used as a control language for large telescopes, you 
should also check with local astronomy clubs. You might also 
call local computer stores to learn of possible computer clubs 
Or user groups in your area. 


ADDITIONAL RESOURCES 1.2 


GETTING STARTED 2 


The FORTH Interest Group publishes a magazine called FORTH 
DIMENSIONS, which contains notices of new groups, conferences, 
and other FORTH activities. FORTH DIMENSIONS includes articles 
of interest to all FORTH programmers. Membership in FORTH 
Interest Group and one year (6 issues) of FORTH DIMENSIONS cost 
$15 (as of December 1981). You should make check or money order 
out to: 


FORTH Interest Group 
P.O. Box 1105 
San Carlos, Ca. 94070 


Or call (415) 962-8653 direct. 
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CHAPTER 2 


* 
* 
* 
* STACKS & NUMBERS 
* 
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* 
* 
* 
* 
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All operations in FORTH are conducted by means of words. 
Some of FORTH's words may not look like words to you-- * / or 
+ for example--but the computer sees them as such. As far as 
FORTH is concerned, any character or group of characters 
separated from other characters or groups of characters by a 
Space on each side is considered a word. For example, 


HELLO $10,000 %%>&& BYE 


are all valid FORTH words. Therefore, you must get into the 
habit now of spacing between each word so that FORTH will 
recognize your commands. 


Numbers are also words in FORTH. Numbers may not contain 
any punctuation and are normally no larger than 32767 and no 
smaller than -32768. (Larger numbers will be introduced in the 
chapter on Advanced Numbers.) Negative numbers are preceded by a 
minus sign. 


1 0 -1 32000 -64 


are all valid FORTH numbers. Numbers are normally acted upon by 
other FORTH words and are saved in a special location called the 
stack." 


2-1 ZHE STACK 


The stack is a "holding file" for numbers that you _ intend 
to work with by means of words. Any number you type onto the 
screen is entered onto the stack awaiting future use. The order 
in which these numbers are stored, however, is of crucial 
importance; you are responsible for understanding how the stack 
works and how to manipulate it to your advantage. 


One of the most familiar ways of imagining the FORTH stack 
is to think of cafeteria trays on a spring-loaded rack. If you 
label three trays 1, 2, and 3 and add them in that order to the 
top of the stack, when you take them off again their order will 
now be reversed: the first one you remove will be #3, the second 
one #2, and the third one #1. You cannot get at tray #1 until 
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you have taken off tray #3 and then tray #2. 
#1 --> _#1_ (top) Push #1 on stack. 


#2 --> _#2_ (top) Push #2 on stack. 
#1 (2nd item) 


#3 --> _#3_ (top) Push #3 on stack. 
#2 (2nd item) 
#1 (3rd item) 


<-- _#2_ (top) Pop (remove) top item. 
#1 (2nd item) 


2-1-1 The Print Command 
The word 
- ( dot ) 


will take whatever is on top of the stack off and display it on 
the screen. This number, you should note, is not on the _ stack 
any longer; if you need to use it for another purpose, you will 
need another operation to save it--more on this later. If you 
type several dots in a_ row, one for each number, FORTH will 
print all the numbers on the stack (in the order we have 
described). Now try this out. Begin by typing a series of 
numbers: 1 2 3 4. Be sure to add enough dots to account for all 
the numbers: 


Le .3 @ ow 2 0 @ 


Now hit the RETURN key to let FORTH recognize the commands, and 
it will answer you: 


4321 OK 


If you type more dots than there are numbers in the stack, FORTH 
will tell you that the stack is empty by displaying an error 
message such as ? EMPTY STACK. Type another dot just to 
check: 


- O ? EMPTY STACK OK 


The concept of a stack must be mastered as you use FORTH, 
as you will often be asked to remember how your information is 
stored there. Furthermore, you will be learning ways to 
manipulate the order of your data on the stack. A convenient 
way to remember the concept is the abbreviation LIFO--Last In 
First Out. 
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2-2 ARITHMETIC OPERATIONS 
2-2-1 Addition 


One of the unusual things about FORTH is the order in which 
the elements of your arithmetic problem--in computer 
terminology, the "arguments"--are entered. Your normal 
inclination might be to write an addition problem like this: 


2% 3 


and with many languages and calculators this would be quite 
correct. In FORTH, however, the same operation would look like 
this: 


23 # 


Why? Mainly because it is simpler for FORTH to handle. Also, 
as you will discover later, this system will eliminate the need 
for parentheses in more complicated algebraic operations. 


But back to our simple addition problem. When you type 
23+ 


and RETURN, FORTH stores 2 and 3 on the stack (in the LIFO order 
just described), adds them, and replaces them with the answer. 
What is now on the stack? Only the answer, 5. When you include 
the dot, the contents of the stack will now appear: 


23+. 5 OK 


Adding a long column of numbers is almost as easy, but you 
must remember to include sufficient + operators. FORTH can 
only add two numbers at ae time. It will take the top two 
numbers you put on the stack, add them, and replace them with 
the answer; then it will take the next number on the stack and 
add that, leaving just the answer, and so on. What you need to 
do is put a + after the first two numbers and after every 
other subsequent number: 


917 + 31 + 47 + 998 + . 1102 OK 
Or the same problem can be written like this: 


9 17 31 47 998 + + + + . 1102 OK 


2-2-2 1+ and 2+ 


For certain frequently performed operations, FORTH saves 
you computer time and space by consolidating the elements ot the 
operation. If you want to add 1 to 14, for example, you could 
use the command 1+ without having to type a1 separately and a + 
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Sign as well. Try this both ways: 
14 1+ . 15 OK 
14 1+ . 15 OK 
Surprise! 2+ works exactly like 1+, except with 2 instead 
of l. 
14 2 + . 16 OK 
14 2+ . 16 OK 


2-2-3 Subtraction 


This operation follows the same basic logic as addition. 
You enter the two arguments (the numbers in your subtraction 
problem), the command for subtraction - , and the dot. FORTH 
destroys the original two numbers and replaces them with the 
answer. 


If you were trying to subtract two from three, for example, 
the usual order "three minus two" would now become "three two 
minus": 

Try a variety of subtraction problems to get comfortable with 
this operation. 


2-2-4 i- and 2- 


Subtracting 1 or 2 from a number is such a common operation 
that FORTH-79 provides separate words for them: 


5 1- . 4 OF 


2-2-5 Multiplication 


The only new thing to learn about multiplication is the 
command for it, which is an asterisk * . (Using an X or a 
dot would be too confusing, as those symbols have other 
functions.) The reverse notation that you learned for addition 
and subtraction still applies. Knowing this, how would you 
multiply 15 by 5? 


15 5: = » 75. OF 
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2-2-6 Division and Remainders 


Division is slightly more complicated because there are 
remainders to deal with. At this point, FORTH can only deal 
with whole numbers; it cannot give you fractions or percentages 
to express remainders. But you can arrange to see the 
remainder, as follows. 


After you type two numbers, the command / (pronounced 
divide) causes the first number to be divided by the second. If 
you tried 


22 3: f OK 
Your answer would be 


- LOK 


If you wanted to know the remainder, you could type the 
same numbers plus a new operator MOD: 


22 3 MOD OK 
and the answer would be the remainder: 


- 1 OK 


A lot of trouble, right? But FORTH has graciously created 
a new word that will do both at the same time: /MOD (pronounced 
divide-mod). It is important, however, to remember to give 
FORTH two print commands, one for the quotient (which will be on 
top of the stack and printed first) and the other for _ the 
remainder (which is next on the stack and printed second). Now 
try out this same problem with /MOD: 


aa 3 JWOD s « 7 1. OF 


2-2-2 2* and 2/ 


While not included in FORTH-79, these words are found in 
the Reference Word Set and are often used in FORTH. They are 
usually written in machine code and are therefore very fast 
operations. As their names imply, they multiply and divide 

by 2: 


5 2% 6 
3 af x K 


2-2-8 Combination Operations 


FORTH can also handle several different kinds of arithmetic 
operations in quick succession. 
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For instance, suppose you wanted to add 15, 37, and 106, 
multiply the result by 5, divide by 7, and see the quotient as 
well as the remainder. You could reduce this to a very concise 
set of instructions, as follows: 


15 37 + 106 + 5 * 7 /MOD . . 112 6 OK 


2-2-2 NEGATE 
The command NEGATE (called MINUS in FIG FORTH) will reverse 
the sign of whatever number is on the top of the stack. Try 
typing a -2 on the stack and changing it with a NEGATE: 
-2 NEGATE . 2 OK 
The same process will work with a +2 (written simply as 2): 


2 NEGATE . -2 OK 


2-2.-10 ABS 


ABS will give you the absolute value of the top number on 
the stack. Try the same two numbers with this new command: 


-2 ABS . 2 OK 
2 ABS . 2 OK 


2-2-ll MAX 
With MAX, FORTH will tell you which of the top two numbers 
on the stack is the greater by removing the smaller number. 
What FORTH will print, then, will be the larger number. Try a 
pair of numbers like 17 and 53: 
17 53 MAX . 53 OK 
-17 -53 MAX . -17 OK 


This will also work with combinations of signed and unsigned 
numbers: 


78 -22 MAX . 78 OK 


2-2-12 MIN 
As yoy might have guessed, MIN will give you the smaller of 
the top two numbers on the stack. The larger number will be 
deleted from the stack, and FORTH will print what is left--the 
smaller number. Try the same sets of numbers: 
17 53 MIN . 17 OF 


78 -22 MIN . —22 OK 
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Why would anyone need a MAX or MIN command? Surely we can 
all tell just from looking whether one number is greater than 
another. But there are useful functions that can be 
accomplished by combinations of these two commands. For 
instance, suppose you would like to exclude numbers from your 
program that are less than -10 or greater than 100. If you put 
-8 on the stack and follow it with -10 and MAX, FORTH will leave 
-8 and delete -10 because -8 is the greater number. 


~8 -10 MAX . ~8 OK 

When you try a number such as -23, your result 
~23 -10 MAX . -10 OK 

will exclude the -23, which is less than -10. 


Half your problem is solved. The other half can be’ solved 
in symmetrical fashion by comparing numbers to 100 using MIN. 
Test this on 56 and 897: 


56 100 MIN . 56 OK 
897 100 MIN . 100 OK 


Lots of work, right? But FORTH will allow you to perform both 
commands one after the other without retyping the original 
number. You type in the number in question and compare it to 
-10; in the same line you compare the result to 100, and FORTH 
will print the result. Look closely at the following example: 


43 -10 MAX 100 MIN . 43 OK 


Read this line the way FORTH reads it. First, 43 is entered 
onto the stack. The number -10 follows. The two numbers are 
compared by means of MAX, and the greater, 43, is left on the 
stack while the lesser, -10, is deleted. 100 is now added to the 
stack, and it is compared to 43 by means of MIN. The resulting 
smaller number, 43, is printed. 


2.2-13 .R and CR 


The command .R stands for right alignment. It is designed 
to set up columnar material in an easy-to-read form. To use .R 
to make columns for a table, for example, enter the number to 
appear in the table, specify the total width of the column (at 
least one character wider than the longest number in the 
series), type the command .R, and use the FORTH word CR 
(carriage return) to start a new line in the table. If you were 
setting up a table with two columns, the width you give the 
second .R will determine the space between the two columns. 


Try this example. You want to set up a two-column table 


with three figures in each. The first column should contain the 
numbers 5, 847, and 1539. The second column should contain the 
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1umbers 46, 395, and 2749. The order of commands should be as 
7ollows: 


CR 5 5 .R 46 5 .R CR 847 5 .R 395 5 .R 
CR 1539 5 .R 2749 5 .R CR 


and the result will look like this: 


5 46 
847 395 
1539 2749 


2-3 STACK MANIPULATION COMMANDS 

FORTH is methodical, thorough, and entirely consistent. It 
will always enter your numbers in LIFO order. There may be 
times when you don't want them in that position, times when you 
want to get at something further down in the stack without going 
through all the numbers on top first. FORTH provides for these 
occasions by offering a small but powerful set of stack 
manipulation commands. 


2-3-1 DUP 
This is an especially useful command for cases when you 

want to use an argument or arguments’ several times or for 
several purposes. DUP simply makes a copy of (duplicates) the 
first (top) number on the stack. If you type in 

5 7 9 OF 
when you printed three dots, you would get 

° o e 9 7 5 OK 
If you type in 

5 7 9 DUP OK 


when you printed four dots this time (to account for the 
duplication), you would get 


° - . e 9 9 7 5 OK 


2.3.2 SWAP 
This command, as its name implies, reverses the order of 
the top two numbers on the stack. If you typed in the same 
series of numbers as before plus a SWAP command, your 
5 7 9 SWAP OK 
would become 


e « +29 508 
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instead of the usual 


ss «s 9 7 5 OF 


2-3-3 OVER 
The command OVER makes a copy of the second number from the 

top of the stack and puts the copy on top, pushing the former 
top number down one place. Your same series of numbers 

5 7 9 OK 
which usually yields 

se 575 OF 
when printed without additional commands, with the addition of 

5 7 9 OVER OK 
will appear like this: 

ee © wD 2. SIO 


(Remember to allow for the duplication of the second number and 
add another dot.) 


2-3-4 ROT 
This command stands for "“rotate;" it removes the third 

number on the stack and puts it on top of the stack, moving the 
other two numbers down to make room for it. In other words, the 
third item becomes the top item, the top becomes the second, and 
the second becomes the third. Your three numbers 

5 7 9 OK 
which usually come off the stack like this 

s . e 9 7 5 OK 
will with the addition of ROT 

5 7 9 ROT OK 
look like this 

« « « 5 9 7 OK 


Remember, this command only changes the order of numbers on the 
stack. None are copied or removed. 
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2-3-2 DROP 


DROP does exactly what it says; it takes the top number off 
the stack and deletes it. Your familiar series 


5 7 9 OF 
would usually yield 


when you printed it. With the addition of DROP, the top number 
on the stack will disappear. 


5 7 9 DROP .. . 7 5 OK 


2-3-6 PICK and ROLL 


PICK and ROLL are generalized stack manipulation words (in 
FORTH-79) . To duplicate the nth-item of the stack and place it 
on top of the stack, use n PICK: 


56768 3 PICK ..6 OF 
4 PICK . 5 OK 


1 PICK is the same as DUP. 2 PICK is the same as OVER. 0 PICK 
(or less) is an error. 


The command ROLL is the generalized form of ROT. n ROLL 
moves the nth number (not counting itself) to the top of the 
stack, moving the remaining values into the vacated position: 


5678 3 ROLL....68750 

5 6:7, 8 #€4 ROLL . « & « K 
3 ROLL is the same as ROT. 2 ROLL is the same as SWAP. 1 ROLL 
takes no action. 0 ROLL (or less) is an error. 


2-4 FORTH NOTATION 


A standard way to indicate changes in the stack is to use 
arrows with the "before" status on the left and the "after" 
status on the right (before --> after). Numbers on the _ stack 
appear in order of entry, so the number furthest to the right 
will be the top number of the stack. Examples appear in the 
following tables. 
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TABLE 2-1 ARITHMETIC OPERATORS 
ACTION 


WORD STACK 
° (nl --> ) Prints number on top of stack. 
+ (nl n2 --> n-sum) Adds two numbers. 
1+ (nl --> nl-plusl) Adds 1 to number. 
2+ (nl --> nl-plus2) Adds 2 to number. 


- (nl n2 --> n-diff) Subtracts n2 from nl. 


l- (nl --> nl-minus1) Subtracts 1 from number. 
2- (nl --> nl-minus2) Subtracts 2 from number. 
* (nl n2 --> n-prod) Multiplies nl and n2. 

/ (nl n2 --> n-quot) Divides nl by n2. 


MOD (nl n2 --> n-rem) Remainder of nl divided by n2. 


/MOD (nl n2 --> 
n-rem n-quot) Divides, leaving remainder 
and quotient. 


2* (nl --> nl-times2) Multiplies number by 2. 

2/ (nl --> nl-divby2) Divides number by 2. 

NEGATE (n --> n) Changes the sign of n. 

ABS (n --> n) Returns the absolute value of n. 

MAX (nl n2 --> n-max) Returns the greater of nl and n2. 

MIN (nl n2 --> n-min) Returns the lesser of nl and n2. 

eR (n width --> ) Prints n as right-justified number 

in a field of width characters. 

CR ( --> ) Emits carriage return (and line 
feed). 
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TABLE 2.2 STACK OPERATORS 


(nl --> nl nil) 


wo STACK 
DUP 
SWAP (nl n2 
OVER (nl n2 
nl 
ROT (nl n2 
n2 
DROP (n --> 
PICK (n --> 
ROLL (n --> 
TABLE 2.1 


--> n2 nl) 


--> 
n2 nl) 


n3 --> 

n3 nl) 

) 
n-picked) 
) 


ACTION 


Duplicates the top number on the 
stack. 


Swaps the top two numbers on the 
stack. 


Pushes a copy of the second stack 
item onto the stack. 


Removes the third item in the 
stack and pushes it on top. 


Removes the top stack item. 

Duplicates the nth stack item. 

Moves the nth stack item to the 
top of the stack, moving the 


remaining items to the vacated 
position. 


ARITHMETIC OPERATORS 


2 


RKKEKEKREKEEKEEKEEKEKEKEKEKEEKEEKKKEKKKKKKE 


* 


CHAPTER 3 


++ + + 


* 
* 
* 
* CONSTANTS, VARIABLES, AND ARRAYS 
* 
* 


KKEKKEKEKEEKEKEKREEEEEEEEKKEREREREKEREKEKKES 


In your work with FORTH, you will occasionally need to set 
up constants and variables that have specific values. As_ their 
names imply, constants have values that never (well, hardly 
ever) change, and variables have values that can be easily 
changed. 


3-1 CONSTANTS 


Setting up a constant is very simple. You specify a value, 
type the word CONSTANT, and then give it a name. Here is an 
example: 


5 CONSTANT DAYS/WEEK OK 


Whenever you want to use this value, you need only refer to its 
name, DAYS/WEEK: 


DAYS/WEEK ._5 OK 


Now that the constant is stored, it has an address--a 
cubbyhole somewhere within the computer, as it were, where its 
name and value are kept. Typing the name of the constant refers 
FORTH to the address, where it finds the value of the constant 
and puts it on the stack to await your command. (FORTH chooses 
the seen by the way, by a system too obscure to worry about 
now. 


3-2 VARIABLES 


Variables are even easier to set up. In FORTH-79, simply 
type the word VARIABLE, followed by the name of the variable: 


VARIABLE RAINFALL OK 
The value of this variable is undefined. To initialize this 
variable to the value 3, type in the following line exactly as 
it appears in the text. (Don't worry about what this line means 
just yet.) 

3 RAINFALL ! OK 


In FIG-FORTH (and most other FORTHs), the initialization is 
combined with VARIABLE, just as it was for CONSTANT: 


VARIABLES 3.2 


CONSTANTS, VARIABLES, AND ARRAYS 16 


3 VARIABLE RAINFALL OK 


In either case, 3 is now the current value of the variable named 
RAINFALL. 


3-2-1 Examining Variables 


The difference between a constant and a variable comes when 
you try to get FORTH to print the value you have assigned. Try 
asking for the value in the same way you would for a constant: 


RAINFALL . 18157 OK 


What happened? The number you got from FORTH (which might look 
like the example we provided or might be a similar large and 
improbable number) is not the value of the variable; rather, it 
is its address. Getting the value of the variable takes an 
additional step: 


RAINFALL @ . 3 OK 


The @ symbol ("fetch") goes to the address that RAINFALL has 
already put on the stack and puts the value it finds there on 
the stack, replacing the address. The dot, as usual, prints 
this number, removing it from the stack. These two operations 
can be combined with a single symbol, the question mark (?). 


RAINFALL ? 3 OK 


Changing the value of a variable is quite simple. You 
enter the new value, type the name of the variable, and add a 
new command ! ("store"). 


Suppose you wanted to change the value of your variable 
RAINFALL from 3 to 6, for example. Your instructions to FORTH 
would look like this: 


6 RAINFALL ! OK 


Be sure you can read and understand this the same way that FORTH 
does. Typing a 6 puts that number on the stack; typing RAINFALL 
puts the address of that variable on the stack as well; ! stores 
the new value at the address on top of the stack, destroying the 
old value in the process. Now when you ask for RAINFALL you 
will get the new value: 


RAINFALL ? 6 OK 
Note: Before you can use the ! ("store") command, a value and 
an address must be on the stack, and the address where you will 


be storing the value must be on top. "Store" needs this 
information to finish its task. 
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3-2-2 Changing Variables 


Using the commands you already know from the previous 
chapter, it is easy to manipulate the value of a variable. For 
example, suppose you have a meteorological variable called 
RECORDHIGH for temperature. Each day you would like to compare 
the value of RECORDHIGH (the highest temperature recorded so 
far) with today's peak temperature (which you have already named 
TODAYSTEMP). If the value of TODAYSTEMP is greater than the 
value of RECORDHIGH, then the value of RECORDHIGH should be 
changed to reflect this. Your problem has two parts: you must 
determine which of the values is greater, and you must order the 
numbers on the stack so that this value will be stored at the 
proper variable. Study the following example, with the 
following given information: the value of RECORDHIGH is 98 and 
the value of TODAYSTEMP is 102. 


RECORDHIGH @ TODAYSTEMP @ MAX RECORDHIGH ! OK 


Make sure you understand how FORTH reads your instructions at 
each point: RECORDHIGH @ puts the current value of RECORDHIGH 
(98) on the stack. TODAYSTEMP @ puts today's peak temperature 
(102) on the stack as well. MAX compares the two and eliminates 
the smaller value from the stack, leaving 102. RECORDHIGH puts 
the address of that variable on top of the stack. The "store" 
command (!) stores the (second) value on the stack at the 
address specified on the stack, destroying the earlier value 
(98) in the variable. What is the current value of RECORDHIGH? 


RECORDHIGH ? 102 OK 


Variables are particularly useful when keeping track of 
running totals. Suppose you are working with two variables, 
TOTALRAIN and TODAYSRAIN. TOTALRAIN (as of yesterday) is 15 and 
TODAYSRAIN is 2. You want to add TODAYSRAIN to TOTALRAIN to 
update your running total. Again, your problem is in two 
parts: you must add the two values, and you must store the 
total correctly. Study the following example: 


TOTALRAIN @ TODAYSRAIN @ + TOTALRAIN ! OK 


Walk through this example to be sure you understand it. 
TOTALRAIN @ puts the value of this variable (15) on the stack. 
TODAYSRAIN @ puts the value of this variable (2) on the stack as 
well. The operator + adds the two values and puts the result on 
the stack, eliminating the two arguments. TOTALRAIN pushes 
(puts) the address of this variable on the stack. The command ! 
Stores the total of 15 plus 2 at the address of TOTALRAIN. 
Check to see what the current value of TOTALRAIN is: 


TOTALRAIN ? 17 OK 


Since keeping running totals is such a common task, FORTH 
has a special command just for this purpose, written +! 
(pronounced “plus-store"). To use "plus-store,”" push the value 
to be added onto the. stack. Then push the address of the 
variable onto the stack. The command +! adds the value on _ the 
stack to the one at the address indicated and stores the result 
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at the address. First, let's set the variable values back to 
the ones you started with: 


2 TODAYSRAIN ! 15 TOTALRAIN ! OK 


The problem you just solved becomes shorter and simpler using 
+13 


TODAYSRAIN @ TOTALRAIN +! OK 
Check to be sure that the result is the same with this method: 


TOTALRAIN ? 17 OK 


When you want to change the value of a variable, the new 
value does not need to come from other already-established 
variables. To FORTH, a value on the stack is a value on the 
stack, regardless of where it came from. 


Therefore, if you wanted to add 4 to the value of your 
current variable TOTALRAIN, you would follow exactly the same 
procedure as you used in the example above: 


4 TOTALRAIN +! OK 


Four is the new value; typing TOTALRAIN pushes its address onto 
the stack; entering +! adds 4 to the old value and stores’ the 
total at TOTALRAIN's address. Check your result: 


TOTALRAIN ? 21 OK 


3-3 CHANGING CONSTANTS 


As with variables, FORTH cannot change a constant without 
knowing its address. Getting the address of a constant is 
different from getting the address of a variable, however. The 
word ' ("tick") will find the address of any FORTH word, 
including constants. Obtaining a typical address this way might 
look like this: 


" DAYS/WEEK . 25614 OK 


When you decide to change a constant, ' will allow you to follow 
the same procedure you used to change a variable. Suppose the 
value of your constant DAYS/WEEK turned out to be in error and 
should have actually equaled seven. Your change would look like 
this: 


7 ' DAYS/WEEK ! OK 
Think about this example for a minute. Typing the number 7 
pushes it onto the stack; entering ' DAYS/WEEK pushes the 


address onto the stack; ! takes the new value and stores it at 
DAYS/WEEK's address, destroying the old value. Now, when you 
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ask for your constant, you get the new value. 


DAYS/WEEK . 7 OK 


3-4 ARRAYS 


Now that you understand how constants and variables work 
separately, it's time to learn how to use them together. A 
logical grouping of identically-sized variables is called an 
array. One of the best reasons for using arrays is saving 
space. It takes a relatively large amount of FORTH space to 
name and store variables, and when they are clustered, more 
Space can be freed for other tasks. As an example, suppose you 
are keeping track of your daily caloric intake and compiling the 
results weekly. If you set up seven different variables, one 
for each day of the week, a great amount of computer space would 
be taken up with the "bookkeeping" tasks of naming, locating, 
and storing so many separate pieces of information. 


The first step in establishing an array is to name _ the 
overall variable. To continue our caloric example, we choose a 
name like CAL/DAY, meaning calories per day. (Long variable 
names also take up unnecessary computer space; abbreviate when 
you can, but don't be too cryptic.) In FORTH-79, you would 
simply type: 


VARIABLE CAL/DAY OK 


In FIG-FORTH (and most other FORTHs), you have no value for this 
variable yet, so simply assign it a value of zero: 


0 VARIABLE CAL/DAY OK 


Your next step is to create enough space in memory for the 
daily subsections of your new variable. How much space do you 
need? Well, every number takes two bytes of computer space; you 
will have a number for each day of the week, so you will need 14 
bytes total. But the value you set for CAL/DAY, zero, takes two 
of these bytes already, meaning that you have only 12 more to 
allow space for. The FORTH word ALLOT will accomplish this 
task. 


12 ALLOT OK 


(Remember to set up your allotment immediately after you 
establish the original variable.) 


At this point you have a long "box" extending from one 
point in the dictionary to another which is included in the 
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variable CAL/DAY. 


Variable CAL/DAY 


2 12 (ALLOT) 
bytes bytes additional 





Your next step is to divide the large box into seven small boxes 
of two bytes each in which to store each day's caloric total. 
Each of these boxes is considered to be at a "constant offset" 
(that is, a set distance) from the beginning of the variable. 
The address of any of these boxes will be the address of the 
variable plus the box's distance from the beginning of the 
variable. 


Start by looking at an index of days (boxes) and their 
distance from the beginning of CAL/DAY. 


0 CONSTANT SUNDAY OK ( Sunday's offset ) 

2 CONSTANT MONDAY OK ( Monday's offset ) 

4 CONSTANT TUESDAY ( Tuesday's offset ) 

6 CONSTANT WEDNESDAY OK ( Wednesday's offset ) 

8 CONSTANT THURSDAY ( Thursday's offset ) 

10 CONSTANT FRIDAY OK ( Friday's offset ) 
( 


12 CONSTANT SATURDAY OK Saturday's offset ) 


Now your long box is divided into seven equal smaller boxes and 
looks (diagrammatically) like this: 


eee Saturday's 
2 bytes 


+12 


Variable CAL/DAY 


Sunday's Monday's 
2 bytes 2 bytes 
+0 +2 


Suppose CAL/DAY's address were 18460; then Monday's calories 
would be located at 18462, Tuesday's at 18464, etc. It is not 
necessary to memorize these specific numbers, as they can always 
be generated by asking for the address of CAL/DAY and adding the 
constant offset. 





How does this work? Study the following example. Suppose 
you consumed 1000 calories on Monday. Your input would be: 


1000 CAL/DAY MONDAY + ! OK 


Entering 1000 puts that number on the_ stack. Typing CAL/DAY 
puts its address on the stack next. Typing MONDAY and then + 
adds 2 to CAL/DAY's address (producing the address of Monday's 
calories) and "store" (!) stores 1000 there ("inside" the 
variable CAL/DAY.) 
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Now, how do we get Monday's caloric record out? Watch: 
CAL/DAY MONDAY + ? 1000 OK 


Review this carefully. CAL/DAY commands FORTH to put its 
address on the stack. Typing MONDAY and + adds two to CAL/DAY's 
address, producing the address of Monday's calories. The 
command ? goes to that address and fetches the value, putting it 
on the stack and then printing it. 


For larger arrays, it is not practical to name each offset 
as a CONSTANT. Instead, the offset must be added directly. For 
example, suppose you were interested in daily caloric intake for 
a year: 


VARIABLE CAL/DAY/YEAR OK ( FORTH-79 ) 
or 
0 VARIABLE CAL/DAY/YEAR OK ( Most other FORTHs) 


followed by 
364 2 * ALLOT OK 


To enter 1000 calories on the 230th day: 
1000 CAL/DAY/YEAR 230 2 * + !_OK 


(The 2 * is necessary because it takes two bytes to store the 
number of calories per day.) 


3-4-1 Arrays of Bytes 


One byte of computer memory can hold any number from zero 
to 255. If the values you put into an array are never less than 
zero or greater than 255, you can effectively double the storage 
space of an array by storing l-byte numbers rather than 2-byte 
numbers. Study the following example: 


VARIABLE MEALS/DAY OK ( FORTH-79 ) 


or 
0 VARIABLE MEALS/DAY OK ( Most other FORTHs ) 
followed by 


5 ALLOT OK ( allocates 5 additional bytes ) 


This sets up an array of 7 bytes. Remember that 2 bytes are 
allocated automatically with each VARIABLE. To store into this 
byte-array, we use the command C! ("c-store"), which is the 
byte-equivalent of ! ("store".) (Historically, the "C" stands 
for "character". Commands which begin with "C" are often used 
to manipulate characters, such as "a" or "b," which occupy one 
byte of memory each.) For example, to specify 4 meals on the 
third day, type: 


4 MEALS/DAY 3 + C! OK 


where 3 is the byte offset of the third day. (Notice again that 
the array actually begins with day zero!) 
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To fetch the value of the third day, use C@ ("c-fetch"), 
which is the byte-equivalent of @ ("fetch"): 


MEALS/DAY 3 + C@ . 4 OK 


Numbers on the stack are normally 2-byte numbers. C! serves to 
pack these numbers into l-byte form, while C@ serves to unpack 
them into 2-byte form again. 


3.4.2 Initializing Arrays 


It is often useful to set up an array of fixed values for 
reference purposes. For example, you may wish to set up an 
array showing the maximum legal fine according to the number of 
moving traffic violations in a given period. Let's assume that 
after five violations, driving licenses are revoked and no 
further fines are possible. One way of doing this is: 


VARIABLE FINE/VIOLATION OK ( FORTH-79 ) 


or 
0 VARIABLE FINE/VIOLATION OK ( Most other FORTHs ) 
followed by 


10 ALLOT OK ( 5 additional 2-byte numbers ) 
0 FINE/VIOLATION 0 + ! OK 


40 FINE/VIOLATION 2 + ! OK 
70 FINE/VIOLATION 4 + ! OK 
100 FINE/VIOLATION 6 + !| OK 
400 FINE/VIOLATION 8 + ! OK 
1000 FINE/VIOLATION 10 + ! OK 


Notice that there are actually six elements in this array, 
beginning with violation number zero. A lot of work, right? 
Fortunately, FORTH provides the command , ("comma") to make this 
initialization easier. This command takes the number on top of 
the stack and allocates it to the end of the most recently 
created variable (or any word). The "comma" should be used 
immediately after the variable is created. We can now simplify 
the above initialization: 


VARIABLE FINE/VIOLATION OK ( FORTH-79 ) 
Q FINE/VIOLATION ! OK 
or 
0 VARIABLE FINE/VIOLATION OK ( Most other FORTHs ) 
40 , 70 , 100 , 400 , 1000 , OK 


Notice that there is no longer a need for 10 ALLOT, since each 
"comma" automatically does a 2 ALLOT. By the way, the 
byte-equivalent of "comma" is C, ("c-comma"). Each C, 
automatically does a 1 ALLOT. 


If you create a variable and immediately type a -2 ALLOT, 
you remove the 2 bytes that are automatically allocated with 
each new variable. You are left with a variable with no 
allocated space. This is often useful (especially with 
byte-arrays) if you intend to initialize each array element, 
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including the zero element: 


VARIABLE PILLS/MEAL OK ( FORTH-79 ) 
0 VARIABLE PILLS/MEAL OK ( Most other FORTHs ) 
followed by 
-2 ALLOT OK 
1 €, 3, Le, 2 C, ox 


PILLS/MEAL might be a byte-array which tells us to take one pill 
at the zero meal (before breakfast?), three pills with 
breakfast, one with lunch, and two with dinner. 


In FORTH-79, we can simply use the command CREATE to create 
a variable that has no storage allocated: 


CREATE PILLS/MEAL OK ( FORTH-79 only ) 
l C, 3 C, 1 C, 2 C, OK 


3-5 TABLES; MORE ABOUT ARRAYS 


This section introduces the FORTH commands ARRAY, CARRAY, 
TABLE, and CTABLE. We have added these commands to the FORTH 
language to make it even easier to use arrays (and tables--see 
below). The FORTH definitions of these words may be found in 
Appendix B. Before reading any further, make sure that these 
words have been added to your FORTH (see chapter 1.0, Getting 
Started). If you like, you may skip this section. 


The actions of creating and allocating storage for an array 
can be combined with the command ARRAY: 


7 ARRAY CAL/DAY OK 


This creates the array CAL/DAY with sufficient storage for seven 
2-byte numbers. The byte-equivalent command is CARRAY: 


4 CARRAY COURSES/SEMESTER OK 


which creates the byte-array COURSES/SEMESTER with sufficient 
storage for four l1-byte numbers. To use these arrays, simply 
push the offset of the element you wish to use onto the _ stack. 
This offset will be automatically added to the address of the 
array, and the result (the real address of the element) will be 
left on the stack (as usual): 


1000 3 CAL/DAY ! OK 
instead of the usua 
1000 CAL/DAY 6 + ! OK 


This will store 1000 into the third element of the array 
CAL/DAY. Notice that it is not necessary to multiply the offset 
by two. Similarly, 


5 2 COURSES/SEMESTER C! OK 


instead of the usual 
5 COURSES/SEMESTER 2 + C! OK 
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means that five courses are being taken during the _ second 
semester. Check again: How many courses are being taken during 
the second semester? 


2 COURSES/SEMESTER C@ . 5 OK 


If the elements of an array seldom change, an array of 
constants would be more useful than an array of variables. Such 
an array is called a table: 


TABLE DISCOUNT/PURCHASE OK 
0,1,2, 4,10, 10, OK 


This creates a table of six constants, starting with element 
zero. Notice that no _ storage is allocated when the table is 
created. To access a constant, simply specify the index 
(offset) of the element: 


2 DISCOUNT/PURCHASE ._2_ OK 
4 DISCOUNT/PURCHASE . 10 OK 


Notice that you don't need to multiply the offset by two, nor do 
you need to "fetch" the value with @. The byte-equivalent of 
TABLE is CTABLE: 


CTABLE DISCOUNT/PURCHASE _OK 
OC, 1 C, 2 Cy 4 C, 10 C, 10 c, ox 
2 DISCOUNT/PURCHASE . 2 OK 
4 DISCOUNT/PURCHASE . 10 OK 
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TABLE 3-1 CONSTANTS, VARIABLES and ARRAYS 


WORD STACK 
CONSTANT <name> 


(n-val -->) 


VARIABLE <name> 


Ee a, 


VARIABLE <name> 


ce 


~— 


Cl 


ALLOT 


C, 


( n-val --> ) 


(address --> n-val) 


(address --> n-val) 


(address --> ) 


(n-val address -->) 


(n-val address -->) 


(n-size --> ) 


(n-val --> ) 


(n-val --> ) 


CREATE <name> ( --> ) 


ACTION 


Creates constant of name <name> 
and value n-val. 


(FORTH-79 usage) 

Creates uninitialized variable 
of name <name>. 

(Most other FORTHs) 

Creates variable of name <name> 
with initial value n-val. 


Replaces address with the value 
n-val found at that address. 


Replaces address with the byte 
value n-val found at that address. 
The high-order byte is set to 0. 


Prints the value found at address. 
Stores n-val at address. 


Stores the low-order byte of 
n-val at address. The byte at 
address + 1 is not disturbed. 


Allocates n-size bytes of storage 
to the last-created word. 


Allocates the number n-val to the 
last-created word. 


Allocates the low-order byte of 
n-val to the last-created 
word. 


(FORTH-79 usage only) 
Creates a variable with name 
<name>, but do not allocate 
any storage to it. 
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TABLE 3-2 ARRAY, CARRAY, TABLE & CTABLE 


WORD STACK 


ACTION 


(The following commands have been added to FORTH. 
See the text for their correct usage.) 


ARRAY <name> (n-size --> ) 


(n-index --> n-adr) 


CARRAY <name> (n-size --> ) 


(n-index --> n-adr) 


TABLE <name> ( --> ) 


(n-index --> n-val) 


CTABLE <name> ( --> ) 
(n-index --> n-val) 


Creates array <name>. n-size 
2-byte elements are allocated. 
In use, the address of the 
n-index element will be left on 
the stack. 


Creates byte-array <name>. n-size 
bytes are allocated. 

In use, the address of the 

n-index byte will be left on 

the stack. 


Creates table <name>. 

Elements are created with "comma." 
In use, the value of the n-index 
element will be left on the stack. 


The byte-equivalent 
of TABLE. 


TABLE 3.1 CONSTANTS, VARIABLES and ARRAYS 


27 


KEEKKKEKEKREKEKEEKKEKKKKEKKEEKEKKKK 


* 


CHAPTER 4 


+e + + 


* 
* 
* WORDS & THE DICTIONARY 
* 
* 


REEEKEKEKKKEKKEKKKKKKKKKKKKKE 


As you have already seen, words are essential to the 
workings of FORTH. All commands in FORTH are accomplished with 
words, each of which has a very specific meaning and must be 
used in the right place in exactly the right order. Where do 
these words come from? Basically, from you. A certain number 
of words are provided for you in this FORTH package, but much is 
left up to the user. FORTH is extensible, in other words; you 
are given the basic tools with which to create new words or 
delete old ones, and then you are left with the freedom to 
define only those that suit your own purposes. 


As with any language, spoken or computed, words can be 
combined to form more complex sentences. It. is to ‘your 
advantage to plan ahead when you define words so as to _ include 
words you have already defined. This is called “modular 
programming," and besides being logically and aesthetically 
pleasing, it saves computer space. Be alert for examples of 
this as you learn about defining words. 


4.1 PRINTING MESSAGES 


Before learning to define new words, you need to learn a 
different type of print command. The dot you were using to 
print numbers from the stack is one type of print command; to 
print messages requires a different type. Perhaps you will 
define a word called GREETINGS which will respond with the typed 
message: 


HELLO! I AM A MESSAGE! 


To make FORTH print this message, it must be surrounded by 
special print commands: 


-" HELLO! I AM A MESSAGE!" 


Notice that the message is preceded by the FORTH command ." 
("dot-quote"). Furthermore, a space separates the ." from the 
HELLO. This space is necessary for FORTH to recognize the 
beginning of the printed message, but it does not move the 
message over one space. Notice also that this space is not 
required before the end quotation mark. The message must contain 
at least one character. 
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4.2 DEFINING WORDS 


The simplest kind of word neither requires arguments from 
the stack nor leaves any results on the stack. Such words are 
useful mostly to present information to the user. The word 
GREETINGS, described above, is an example of such a word. Let's 
see how we might define it. 


Definitions always start with a colon (:). The colon's 
meaning is that a definition follows immediately; like any other 
word, it is followed by at least one space. The next element 
must be the name of your new word. So far you have entered the 
following: 


: GREETINGS 


Since your message starts on a new line, you must first tell 
FORTH to return the carriage. You already know the word that 
performs this function, CR. Next, you want to tell FORTH what 
the printed message will be and _ surround this by the print 
command you have just learned. Your definition now looks’ like 
this: 


: GREETINGS CR ." HELLO! I AM A MESSAGE!" 


The last instruction to be added is a semicolon (;), which lets 
FORTH know that the definition is over. Again, the semicolon is 
a word and must have a space before it. Your final definition 
looks like this: 


: GREETINGS CR ." HELLO! I AM A MESSAGE!" ; 


and when you press the RETURN key, FORTH will compile the new 
definition, responding with its usual OK. Now when you ask for 
GREETINGS, FORTH will type the message as you intended. 


4.3 VLIST 


All the words in FORTH, including the one you just 
compiled, exist in a long list called, naturally enough, a 
dictionary. You will often want to check this dictionary to see 
whether a particular word has been defined yet. All FORTHs have 
a command to let you see a list of the words currently in your 
dictionary. This command might be called HELP or LIST-WORDS or 
something similar. In MicroMotion FORTH-79 and FIG-FORTH, this 
command is VLIST (vocabulary list). To see your. current 
dictionary list, simply type VLIST (or the equivalent command). 
In many FORTHs, you can press the space bar to halt the listing 
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and the carriage return key to exit the listing. 


VLIST 


This is the format of the simple VLIST in MicroMotion FORTH-79. 
Your VLIST may have a different format. Notice the top word in 
the dictionary; it is GREETINGS, the word you most recently 
defined. Like the stack, the VLIST will always show you _ the 
word last entered on top. MicroMotion also supplies a more 
sophisticated VLIST which, along with the name of the word, 
provides the machine address of the word (in hexadecimal base) 
and notes whether the word is one of several special types. For 
details see appendix A, C and M. 


4.4 FORGET 


Perhaps you don't like a word you have just defined. You 
might have a better one now, or you might have found a lot of 
errors and just want to start over. Maybe you were just 
experimenting anyway and never intended to keep the word 
permanently. FORGET is for you; your word will be erased from 
the dictionary with this command. Why don't we get rid of 
GREETINGS: 


FORGET GREETINGS OK 


Check to see that GREETINGS no longer appears in the 
dictionary: 


VLIST 


SETINV 
SETNORM 
PBUTTON 
PADDLE 


Special note: When you pick a word and ask FORTH to FORGET it, 
it will erase that word and every word entered after it as 
well. If you typed 


FORGET SETNORM 


you would also lose SETFLASH and SETINV. If you decide in the 
middle of a definition that it is just not worth working with, 
finish the definition with a ; (compiling the word) and then 
FORGET it. Words that turn out to produce errors can also haunt 
you later; be sure to FORGET all of them. 


Note: Some FORTHs feature dictionary protection to keep you from 


forgetting critical words. The MicroMotion FORTH protection 
method is described in appendix J. 
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4.5 MORE DEFINITIONS 


This section introduces the FORTH command RANDOM which will 
be used within other definitions. The FORTH definition of this 
word may be found in appendix B. Before reading any further, 
make sure that RANDOM has been added to your FORTH (see chapter 
1, Getting Started). 


Sometimes a word does not need arguments on the stack but 
does leaves results on the stack. For example, such a word 
might use the command RANDOM, which generates random numbers. 
RANDOM will generate and add to the stack a number within a 
range that you set. (Specifically, n RANDOM will generate a 
random number between 0 and n-l, replacing n with the number). 
You could ask for a random number between 0 and 9, for example: 


10 RANDOM . 5 OK 


RANDOM can be used to simulate chance events, such as you 
might find in gambling. You can define the word DICE, for 
example, which will show you the numbers on top of two dice each 
time you throw them. Think about your problem for a minute. You 
must generate two random numbers between 1 and 6; it will not do 
to generate 0, as might happen with RANDOM, so you must think af 
a way to eliminate this possibility. Here is one way: 


: DICE 6 RANDOM 1+ . 6 RANDOM 1+. ; 


: DICE 

6 puts 6 on the stack. 

RANDOM generates a number between 0 and 5, 
replacing the 6 with this number. 

1+ adds 1 to the number you just generated; 
instead of a number from 0 to 5, 
you now have a number from 1 to 6. 

° prints the resulting number. 

6 puts another 6 on the stack. 

RANDOM generates yet another random number 
between 0 and 5. 

1+ adds 1 to this number. 

. prints this number. 

3 ends the definition. 


Now try out your new word: 
DICE 
DICE 
DICE 2 2 OK 


The word DICE can be embellished by adding a message with the 
print command you learned earlier (."): 


: DICE CR ." THE THROW OF THE DICE IS " 
6 RANDOM 1+ . 6 RANDOM 1+ . ; 


When you compile DICE a second time, many FORTHs will warn you 
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that you have used a word twice with a message such as 
DICE ISN'T UNIOUE OK 


You can still proceed with your second definition; both will be 
recorded on VLIST, but only the most recent definition (the 
second one) will actually be used when you call for it. Try 
your new word DICE to see what you get: 


DICE 
a OF THE DICE IS 4 1 OK 


THE THROW OF THE DICE IS 3 5 OK 
DICE 


THE THROW OF THE DICE IS 2 4 OK 


If you now FORGET DICE, only the most recent definition (and any 
words defined after it) will be forgotten: 


FORGET DICE OK 
DICE 3_5 OK 


Another kind of definition both requires arguments on the 
stack and leaves results on the stack. The arithmetic operators 
you learned in chapter 2 ( +, -, * ) are examples of this’ type. 
A more complex example might be a word like DOZENS, which will 
take a number you provide and tell you how many dozens are in it 
with what remainder. Like the preceding definition, this one 
will incorporate a message. After you type a number and DOZENS, 
you want FORTH to start a new line, print the number of dozens 
followed by the message "DOZEN PLUS" and then type the 
remainder. You already know all the words necessary to create 
this definition: 


: DOZENS 12 /MOD CR. ." DOZEN PLUS". ; 


Be sure that you can identify the purpose of all the elements in 
this definition: 


: DOZENS 

12 puts 12 on the stack. 

/MOD divides the number you specify by 12 
and puts the quotient on top of the 
stack with the remainder second, 
replacing the original number. 

CR starts a new line. 

° prints the top number on the stack, 


which is the quotient. 
-" DOZEN PLUS" prints the message DOZEN PLUS. 


° prints the second number on the 
stack, which is the remainder. 
: ends the definition. 
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Now try out your new problem-solver: 


367 DOZENS 
30 DOZEN PLUS 7 OK 


4.6 THE DICTIONARY 
The FORTH dictionary, as we have mentioned, operates like 
the stack; the last definition compiled is on top of the VLIST. 
Here is a simplified diagram of how the FORTH-79 dictionary is 
put together: 


@———-- HERE (next available word location) 






NAME 






*x 
meee Most recently defined word 


----------- Link to previous word 


Parameter 
field 






Previous 
words 


Each FORTH word exists in one of the boxes. The box includes 
the name of the word, information specifying the location of the 
previous word, and the parameter field. The parameter field for 
variables, constants, and arrays is the storage space for 
numbers. For other words, the parameter field includes the code 
to be executed when the word is run. 


The word HERE pushes’ the address available for the next 
dictionary entry onto the stack. 


HERE . 14178 OK 


In this case, the next word you define will begin at address 
14178. HERE pushes its value on the stack, like any constant. 
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But the value of HERE changes whenever the dictionary grows: 


HERE . 14178 OK 
VARIABL 
HERE . a OK 


2 ALLOT 

HERE . 14188 OK 
izes 

HERE . 14188 OK 
e oO . 3 IK 
: TEST ; 

HERE . 14197 OK 


During a FORTH session, you may experiment with many 
definitions, and at the end you might want to erase all of these 
experiments, leaving the permanent words below. One way to 
accomplish this efficiently is to define a "dummy" word before 
you start; when you are ready to erase, you tell FORTH to FORGET 
the dummy word, and everything else above is also erased. A 
typical dummy word is TASK: 


which executes nothing at all. 


4-2 SAVING THE DICTIONARY 


Most FORTHs provide a command which lets you save your 
dictionary, with all newly compiled words, on an external mass 
storage device. The next time you sit down at your terminal, 
you should be able to recover a copy of the dictionary you last 
saved. This lets you continue programming over several 
sessions. 


In MicroMotion FORTH-79, this command is called SAVE. Here 
is a typical SAVE format: 


SAVE 
25 SCREENS OK 


The next time you boot up on the diskette, you will be given the 
most recently SAVEd dictionary. 
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TABLE 4.1 WORDS AND THE DICTIONARY 


WORD STACK ACTION 
: : <mame> ... Creates dictionary entry for the 
( --> ) word <name>. Begins compilation. 
? <name> ee. } Terminates dictionary entry for the 
( --> ) word <name>. Stops compilation. 
“ ” eececc" Prints text cccccc (up to "). 
( --> ) If ." is included in the definition 


of a word, printing will take place 
when the word is later executed. 
The text cccccc must include 

at least one character. 


FORGET FORGET <name> Deletes the word <name> from the 
dictionary. Also deletes all words 
added after <name>. 


HERE ( --> address ) Returns the address of the next 
available dictionary location. 


(The following commands may have a different name or slightly 
different action in your FORTH.) 


SAVE ( ==> ) Saves the dictionary with all 
currently defined words on an 
external mass storage device. 
The next time you begin a FORTH 
session, you will be given the 
dictionary which you saved last. 


VLIST ( --> ) Lists the words currently in your 
dictionary, starting with the one 
most recently defined. 


(This command has been added to FORTH. You will find the 
definition in appendix B.) 


RANDOM ( n-limit --> n ) Returns a random number ranging 
from 0 to n-limit minus l. 
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Now that you have learned how to create simple definitions, 
you can build into them ways to make decisions based on criteria 
you supply and to repeat operations within limits you specify. 
These are called flow of control operations; they may be written 
into the definition of any word. In fact, flow of control words 
can only be used within definitions. 


2-1 DEALING WITH DECISIONS 


Many games, for example, use structured operations. Games 
involving dice often have elaborate branched structures which 
depend on the throw of the dice at each branch. Think of the 
decisions involved in playing craps. Your first throw of the 
dice could be a 2 or a 12 (snake eyes or boxcars), in which case 
you would lose. Or it could be a7 or anl1ll (craps), in which 
case you would win. If neither, the sum of the throw would be 
recorded and you would continue to throw. If the throw equaled 
your previous sum, you would win; if it equaled 7, you would 
lose. If neither, you would keep rolling until you won or 
lost. Programming FORTH to play craps would first involve 
checking the sum of the dice for 2 or 12, 7 or 1l, and deciding 
what to do based on the result. FORTH would save the result, if 
neither condition were filled, and continue rolling the dice 
until certain other conditions were filled, checking each time 
before rerolling. Each time it checked it would get a "yes" or 
"no" answer on which it would base its next action. 


In executing the decisions and limits you establish in your 
structure, how does FORTH deal with yes and no answers? By 
means of "logical operators" or "truth functions." Before you 
proceed with flow of control problems, you must understand how 
these operators work and how they differ from each other. 


S-l.l1 Logical Operators 


All the decisions that FORTH makes are expressed as true or 
false, yes or no, zero or non-zero. Logical operators allow you 
to "test" numbers for various properties--same, different, above 
zero, below zero--and always return an answer of true or false. 


Before we begin, let's define a word which will print 
"TRUE" if the value on top of the stack is true and "FALSE" if 
the value is false, removing the value from the stack in the 
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process. Type the following--don't worry what it means just 
yet; it will be explained below: 


: TRUTH IF ." TRUE " ELSE ." FALSE " THEN ; 


Now try out some values with this word. 


0 TRUTH FALSE OK 
1 TRUTH E_OK 


50 TRUTH TRUE OK 
-3 TRUTH TRUE OK 


Any non-zero number is considered true; zero is the only number 
that will give you a false response. 


The operator AND can be used to test whether the two top 
numbers on the stack are both true. 


Note: AND is a "bitwise" AND, so it is not enough for the 
numbers to be non-zero, as in TRUTH; they must both be ones. 


Since most logical operators leave a zero (false) or a one 
(true) on the stack, this is seldom a problem: 


1 0 AND TRUTH FALSE 
0 1 AND TRUTH FALSE 
0 0 AND TRUTH FALSE OK 
1 1 AND TRUTH UE OK 

2 4 AND TRUTH FALSE OK 


The word OR will give a true response if either of the 
arguments is non-zero. Try 1 and 0 again: 


1 0 OR TRUTH TRUE OK 


2 and 3 would yield the same answer: 
2 3 OR TRUTH TRUE OK 


because at least one argument is non-zero. The only way to get 
a false response would be to try two zeros. 


0 0 OR TRUTH_FALSE OK 
Incidentally, OR is a "bitwise" OR. 

The commands < (less than) and > (greater than) will test 
two arguments for their value relative to each other. The first 
argument is compared to the second. Try 2 and 4: 

2 4 < TRUTH TRUE OK 


FORTH is telling you that 2 is indeed less than four. Try the 
greater than symbol: 


2 4 > TRUTH FALSE OK 
—eee ee 


2 is not greater than 4. 
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The word = will test for the equality of two arguments. 
Test this with 1 and 3: 


1 3 = TRUTH FALSE OK 
and 3 and 3: 


3 3 = TRUTH TRUE OK 


The word - ("minus"), as you recall from the arithmetic 
operators section, subtracts the top number on the _ stack from 
the second. If equal numbers are subtracted, the answer is 
zero; if unequal numbers are subtracted, the answer could be any 
number, positive or negative, except zero. Can you now see how 
- could be a test for inequality? The zero result obtained by 
subtracting equal numbers would be expressed as FALSE; the 
non-zero result of subtracting unequal numbers would be 
expressed as TRUE, Try this out on the same pairs of numbers 
that you used for = : 


1 3 - TRUTH 
3 3 - TRUTH FALSE OK 


If using - seems awkward, you can rename it--perhaps 
UNEQUAL. The definition of UNEQUAL will be the word - : 


: UNEQUAL - ; 


Now when you try the same operations, the results will be easier 
to interpret: , 


1 3 UNEQUAL TRUTH 
3 3 UNEQUAL TRUTH F E_ OK 


The word O0= is tricky at first because it reverses’ the 
answers you have come to be familiar with. This word will tell 
you whether an argument is equal to zero; if it is, your answer 
will be TRUE. You will want to be able to do this in future 
flow of control operations when it is necessary to check for the 
presence of a zero on the stack. See how this works: 


4 O= TRUTH F 
-15 O= TRUTH FALSE OK 


0 O= TRUTH TRUE OK 


You can also rename O= to NOT: 


: NOT O= ; 
4 NOT TRUTH K 


0 NOT TRUTH TRUE 


The operator O0< will tell you if an argument is less’ than 
zero--a negative number. Negative numbers, then, give a TRUE 
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response; numbers 0 and above give a FALSE answer. 


5 0< TRUTH SE OK 
-5 O< TRUTH 


Finally, FORTH-79 includes the command 0> , which tests’ to 
see whether its argument is one or greater: 


-1 0> TRUTH FALSE 
0 0> TRUTH SE OK 
10 0> TRUTH TRUE OK 


2-1.2 Conditional Structures 


Within conditional structures, FORTH will make decisions 
according to criteria you specify and perform operations based 
on those decisions. FORTH first looks at the argument 
(condition) on top of the stack and examines it for its truth 
value; if true, it does one thing, if false, it does another, 
and then it moves on. The operations FORTH performs could be 
anything; if an argument is true, you could command FORTH to 
print the word TRUE (or the word PANAMAHAT) or store the value 
at a certain address or multiply it by 6 ....anything you want. 


The form that this structure must take is strictly ordered, 
however: 


: DEFINITION condition IF one thing 
ELSE the other thing THEN move on ; 


Be sure you know what is happening at each stage of this 
structure: 


: DEFINITION 

condition you enter the argument at this point 
plus any manipulations that will 
lead to a zero (false) or non-zero 
(true) result on top of the stack. 

IF FORTH tests the condition for truth 
value. If true, it goes straight 
on; if false, it skips to ELSE 
or THEN, whichever appears first. 
The condition is removed from the 


stack. 
one thing FORTH executes the command. 
ELSE if the condition was false, FORTH 


skips to this point. 
other thing FORTH executes this second 
command rather than the first. 
THEN ; after FORTH has considered the 
IF/ELSE choice, it stops the 
process and moves on to your next 
command (if any). 
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Notice that the ELSE section is optional; if the condition turns 
out to be false, you may want FORTH to ignore it entirely, in 
which case FORTH would simply move to THEN and end the 
structure. 


The word TRUTH that you have been using up to now is a good 
example of a conditional structure. Look at the definition 
again: 


: TRUTH IF ." TRUE " ELSE ." FALSE " THEN ; 
Examine this definition one step at a time: 


: TRUTH 

(condition) the condition, in this case, is the 
argument to TRUTH, which is already 
on the stack. 

IF FORTH tests the condition for truth 
value, going to ELSE or THEN 
depending on the result. The 
condition is removed from the stack. 


o" TRUE * if the condition was true (non-zero), 
FORTH prints TRUE. 

ELSE if the condition was false (zero), 
FORTH comes to this section... 

-" FALSE " eeeand prints "FALSE." 

THEN ; the structure is finished. 


FORTH marches on. 


A more complicated type of IF...ELSE...THEN structure 
involves two or more mutually exclusive choices. It is quite 
possible to order each choice independently, that is, to have 
FORTH look for one condition, execute a command you specify, 
then look for another condition with a new operation, and so 
on. However, with mutually exclusive choices, the first 
IF...-ELSE...THEN structure limits the need for further checks. 
For example, if you are checking to see if a value is 5, 3, or 7 
and the value happens to be 5, there is no need to ask whether 
it is 3 or 7. For maximum efficiency, you would want FORTH to 
skip the next two questions. If you use three independent 
IF...ELSE...THEN structures, this economy is not possible. 
Therefore, you should learn to use a "staircase" or "case" 
structure for these situations. If you diagrammed the process 
FORTH uses to implement such a structure, it would look 
something like this: 


IF ( yes? then execute following command and go to 
outermost THEN ) 
ELSE ( no? then try second question ) 
IF ( yes to second question? then execute 
second command and move to innermost THEN ) 
ELSE ( no? then execute third command and 
move to innermost THEN ) 
THEN ( stop innermost structure ) 
THEN ( stop outermost structure ) 
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An interesting example of such a structure might be the word 
-DICE. This word, like the word DICE that you defined in 
chapter 4, throws dice but also checks them for certain 
combinations--snake eyes (1 and 1) and boxcars (6 and 6). If 
the answer to either of these checks is 1 (true), it will tell 
you by printing SNAKE EYES or BOXCARS. If neither is true, 
FORTH will do nothing except print the throws themselves. The 
throws of the dice will be left on the stack for possible future 
use. 


As you think about how to order your definition of .DICE , 
remember that many of the operations (arithmetic operators, 
logical operators, IF) that you will perform on the numbers’ you 
generate will destroy these numbers. You must think ahead of 
time about duplicating these numbers so that they will not be 
lost. Also, it is a good idea to form the habit of "commenting" 
on your definition. These comments will include notes on what 
is added to and left on the stack and summaries of what each 
section of the definition does. Comments should begin with the 
word ( ("paren"). Because ( is a FORTH word, it must be 
followed by at least one space. 


Now try formulating a definition. It might look like 
this: 


DICE 
6 RANDOM 1+ 6 RANDOM 1+ ; 


: eDICE ( --> DIE-l DIE-2 ) 
DICE OVER OVER CR. . 
OVER OVER + ( FORM SUM ) 
DUP 2 = 
IF ( SNAKE EYES? ) 

-" SNAKE EYES " DROP 
ELSE 12 = 
IF ( BOXCARS? ) 
-" BOXCARS " 
THEN 
THEN ; 


Notice the new definition of DICE. Check to be sure you know 


DEALING WITH DECISIONS 5el 


FLOW OF CONTROL 42 


the purpose of each word in the definition: 


: DICE 
DICE generates two random numbers 
between 1 and 6 and places them 
on the stack. 
OVER OVER copies and moves the two numbers; 
now you have two sets of random 
numbers, each in the original 


order. 

CR returns the carriage for a new line. 

- prints the first set of numbers, 
destroying them. 

OVER OVER creates another duplicate pair of 
numbers. 

+ adds the top two numbers, destroying 
them and leaving the sum on the 
stack. 

DUP makes a copy of the top number (the 
sum). 

2= checks to see if the sum is equal to 


2; if yes, then a true condition 
is placed on the stack, destroying 
the sum and the number 2. 

IF removes the condition from 
the stack, checking to see whether 
it is true. If yes, it executes 
the next command and moves to the 
outermost THEN. If no, it 
proceeds to ELSE. 

-" SNAKE EYES " prints this message. 

DROP drops the top sum from the stack, 
leaving only the original throw. 
FORTH now proceeds directly to 
the outermost THEN. 

ELSE 12 = checks the sum to see if it is equal 
to 12, destroying the sum and the 
12 in the process. If yes, the 
next command is executed and FORTH 
moves to the innermost THEN; if 
no, FORTH moves directly to the 
innermost THEN. 


-" BOXCARS " prints this message. 

THEN THEN stops the innermost and outermost 
structures. 

; stops the definition. 


Now try out your new word: 


eDICE . . ( DROP RESULTS FOR NOW ) 
1 1 SNAKE EYES 1 1 OK 
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2-2 LOOPS 


Loops come in two basic types: finite and indefinite. 
Finite loops are set up to repeat a given number of times; 
indefinite loops continue until a certain condition is fulfilled 
one a given event occurs, regardless how many repetitions this 
takes. 


2-2-1 Finite Loops: DO LOOP. 


This control structure will repeat a given set of commands 
as many times as you specify--from an initial value to an upper 
limit. FORTH will repeat the operation once per unit within 
this range. 


For FORTH to perform the usual stack operations and print 
your commands as well as keep track of how many times it has 
repeated a given operation, another type of stack is required. 
What we have been calling the "stack" is correctly termed the 
"parameter stack"; the new stack we are introducing now is 
usually called the "return stack." 


One of the simplest kinds of finite loops is one that will 
print a series of numbers between limits you specify. You could 
decide to print a list of numbers from 1 to 10, for example. To 
do this, you will need to do the following: 


1. Name the definition. 

2. Set up the initial loop value and upper limit. 

3. Use DO to move these loop parameters to the 
return stack. 

4. Start the loop. 

5. Move a copy of the top number on the return stack, 
Called the "index," to the parameter stack. 

6. Print this number. 

7. Use LOOP to add one to the index on the return 
stack. 
If the index is now equal to the upper limit, 
remove the index and upper limit from the return 
stack and exit the loop. 
Otherwise, continue the loop (at step 5). 


For aesthetics, it is also useful to add a carriage return (CR) 
between each number to make a vertical list. Your result should 
look like this: 


: NUMBERLIST 11 1 DO CR I . LOOP ; OK 
Why is your limit 11 instead of 10? FORTH will stop executing 
the commands within the loop when the current number on top of 
the return stack (the index) equals or exceeds the upper limit. 
Always remember to add one to the limit when setting up a list 
like this. 


Just to check, walk through the definition to be sure you 
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know what each element does. 


: NUMBERLIST 

11 puts 11 on the parameter stack. 

1 puts 1 on the parameter stack. 

DO starts the loop and moves the loop 
parameters to the return stack. 

CR returns the carriage to start the 
list. 

I copies the index from the top of the 
return stack to the parameter 
stack. 

. prints whatever is on the 
Parameter stack. 

LOOP ; increments the index by l. 


If the index equals ll, exits the 
loop and removes the index (11) and 
the upper limit (11) from the 
return stack. 

Otherwise, start the process over. 


Try your loop and see what you get: 


NUMBERLIST 


Ne 


RO KON I) pre pw 


10 OK 


A further variation on the DO LOOP procedure involves use 
of the word +LOOP. Instead of incrementing the index by one 
each time the loop repeats, you can determine the increment 
yourself. For instance, you could do the list from 1 to 20 by 
threes. The definition would be only slightly changed: 


: NUMBERLIST 21 1 DO CR I . 3 +LOOP ; OK 


Note that the increment should immediately precede the +LOOP. 
Your results will now look like this: 


NUMBERLIST 


9 =e 


12 OK 
A more complicated kind of loop is a "nested loop"--a loop 


within a loop. One thing such a structure could do is take a 
list and compare each item in that list to all the items in a 
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second list. One word that uses such nested loops is ODDS, 
which examines probabilities in dice-throwing. Taking the sum 
of the numbers on the two dice, it is clear that some sums will 
occur more often than others because there are more combinations 
of numbers that can equal them. A sum like 2 could only be 
formed one way (1 + 1); on the other hand, 7 might be formed 
several ways. ODDS will tell you how many possible ways there 
are to make a given sum out of the 36 possible combinations of 
numbers on the two dice (6 X 6). 


The word ODDS must do several things, then. It must first 
compare a sum that you provide to every possible sum of dice 
values. The first time it finds a combination that leads to the 
same sum as yours, it will put al (true) on the stack. Each 
successive equality it finds will increment this stack number by 
one. The final count on the stack will be the total number of 
possible combinations. After you print this, there will be 
nothing left on the stack. 


How do you use nested loops? You have two lists, one for 
each die, each from 1 to 6. You must compare a1 on the first 
die to every possible number on the second die, then a 2 to 
every possible number, and so forth. You cannot increment the 
first loop until you have completed the second loop entirely. 
Therefore, the second loop is "nested" inside the first. To 
handle two lists at the same time, you will need one additional 
command. The word I copies the index of a loop to the parameter 
stack for manipulation; if you have two loops being operated on 
at the same time, you must have another command to get at the 
index of the first loop, which is put on the return stack first 
and is therefore further down. Stack manipulation commands do 
not work on the return stack. The command J will work for this 
second outermost loop. In this case, J is the index of the 
first die; I will index the innermost loop (the second die). 


Now you are ready to write the definition for ODDS: 


: ODDS (sum of throw --> ) 
0 SWAP 
7 1DO (J LOOP ) 
7 1DO (I LOOP ) 


DUP IJ + = 
IF SWAP 1+ SWAP 
THEN 
LOOP 
LOOP 


DROP CR..." OUT OF 36 WAYS " ; 


LOOPS 5.2 


FLOW OF CONTROL 46 


Several elements of this definition are worthy of note: 


: ODDS 

0 SWAP puts the count (0) on the stack 
and SWAPs it with the sum you 
are looking for so that the 
sum is again on the top of 
the stack. The count (0) is 
the number of combinations 
found so far. This count will 
be incremented by the number 
of possible combinations you 
find later. 

7 1 DO establishes the parameters of 
the outermost (J) loop. 

71 DO establishes the parameters of 
the innermost (I) loop. 

DUP copies the sum you are seeking. 

I J + takes the first die (I) and the 
second die (J) and adds them. 

= checks if this is the sum you 
are looking for (true or 
false). 

IF tests the condition and removes 
it from the stack. If true, 
continue with the next 
statement. If false, skip to 
the nearest THEN. 

SWAP 1+ SWAPs the sum and count. 

Adds 1 to the count, which is 
now on top of the stack. 


SWAP moves the sum you are looking 
for back to the top. 

THEN ends conditional structure. 

LOOP LOOP ends I and J loops. 

DROP CR drops original sum and returns 
carriage. 

e prints number of possible 
combinations. 

-" OUT OF 36 WAYS " prints this message. 

; ends definition.. 


What do you get when you try ODDS? 


4 ODDS 
3 QUT OF 36 WAYS OK 


2 ODDS 
1 QUT OF 36 WAYS OK 


2-2-2 Indefinite Loops 
Indefinite loops also come in two types, those that are 
waiting for a true (non-zero) response to stop (BEGIN...UNTIL) 


and those that are waiting for a false (zero) response 
(BEGIN...WHILE...REPEAT). 
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2.2.3 BEGIN...UNTIL. 


This loop will repeat a given operation until a certain 
condition is "“met"--that is, until it sees a true (non-zero) 
condition on the stack. Between the words BEGIN and UNTIL are 
words which manipulate the stack material that ultimately lead 
a this true or false result. UNTIL removes this condition from 
the stack. 


An example of a task this loop might perform is something 
we will call DOUBLES, which will "throw dice" (generate random 
numbers) until it gets doubles and will then _ stop. The word 
will first announce its intention (by printing "LET'S THROW 
DOUBLES!") and then start generating and printing pairs of 
random numbers. After each throw it will check to see if the 
two numbers left on the stack are equal; if yes, it will stop, 
and if no, it will return to the beginning of the loop. Here is 
the definition of DOUBLES: 


: DOUBLES ( --> ) 
CR ." LET'S THROW DOUBLES! " 
BEGIN .DICE = UNTIL ; 


Note that the message is not included in the loop. If it were, 
it would be printed each time a new pair of numbers were 
generated; all you want it to do is print at the beginning of 
the search. Now try out DOUBLES: 


DOUBLES 
= THROW DOUBLES! 


ROME ee 
REP ME 


OK 
DOUBLES 
LET'S THROW DOUBLES! 
6&3 
42 
12 
& & BOXCARS OK 


A slightly more complicated task for BEGIN...UNTIL to accomplish 
is to check the throw of the dice to see if their sum is an even 
number. See if you understand all the elements in the 
definition: 


: EVENS ( THROW DICE UNTIL THROW IS EVEN ) 
BEGIN 
DICE 
CR OVER OVER . . OVER OVER + 2 MOD 0= 
UNTIL 
CR ." EVEN THROW IS"... ; 


LOOPS 502 


FLOW OF CONTROL 48 


Note that "checking for evenness" can be expressed as 2 MOD 0= 
--that is, dividing by two and checking to see if the remainder 
is 0. Now try out your new definition: 


It's a good habit to check the stack after you define a word to 
see what is left there. Type a few print commands to check: 


Where did all these numbers come from? They must be all the 
dice throws that were rejected, the ones that added up to odd 
numbers. The definition works, of course, but you don't want to 
clutter up the stack with rejected numbers. In some FORTHs, the 
computation stack is quite small and if it "overflows," you will 
destroy your system. Something should be built into the 
definition to drop these numbers. 


That something is the "detour" section of the structure, 
called WHILE. It functions like ELSE in the IF...ELSE...THEN 
structure; it performs a second command whenever the condition 
does not fulfill your criteria. This command could be to drop 
the offending numbers, to print out an explanatory message, or 
to perform any other task. 


There are a few notable differences in this new structure, 
called BEGIN...WHILE...REPEAT. Most important, the condition 
you are hoping to find (which will end the loop) will put a 
false condition (zero) on the stack, not a true condition 
(non-zero number). The WHILE section will be executed (and the 
loop repeated) if the condition puts a true condition on the 
Bpeeks Like BEGIN...UNTIL, the condition is always removed from 
the stack. 


You can use WHILE to dispose of the unwanted (odd) throws 
in EVENS. You might remove the offending numbers from the stack 
by printing them; you might also simply drop them. In this 
case, you will print them with an explanatory message. Study 
the following definition carefully: 


: EVENS2 ( THROW DICE UNTIL THROW IS EVEN ) 
BEGIN 
DICE 
OVER OVER + 2 MOD 
WHILE 
CR ." ODD THROW IS ".. 
REPEAT 
CR ." EVEN THROW IS"... ; 


Be sure you understand what is on the stack at each point. 
After the 2 MOD section, there is either a one or a zero on the 
stack. If it is one (meaning an odd number), the WHILE section 
will be executed and the loop repeated. If zero (meaning an 
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even number), the structure will skip the REPEAT section and 
print the message following it. 


Now try out the definition and check the stack to see if 
anything is left there. 


EVENS2 
EVEN THROW IS 5 3 OK 


EVENS2 
QDD THROW IS 5 4 
EVEN THROW IS 5 1 OK 


° « « « O ? EMPTY STACK 


It works! Congratulations on fixing your first bug. 


2-3 ANOTHER DUP 


Because the word LOOP (or +LOOP) lies at the end of the 
DO...-LOOP (or +LOOP) structure, you will always execute a loop 
at least once, even if the initial lower limit already equals 
(or exceeds) the upper limit: 


: TEST 0 0 DO I. LOOP ; OK 
TEST 0 OK 


To prevent this, you can usually rewrite your loop so that if 
the initial lower limit of the loop is zero, the loop is 
skipped. For example, the following word COUNTUP counts (and 
prints) up to whatever limit you push on the stack, starting 
with one. If the limit is zero, it does nothing: 


: COUNTUP ( n-limit --> ) 
DUP ( IF NOT ZERO ) 
IF 1+1 
DOI. 
LOOP 
ELSE DROP 
THEN ; OK 


3 COUNTUP 

0 COUNTUP 
Notice the need for an ELSE clause to DROP the unwanted initial 
zero. This construction, and its variations, are so common in 
FORTH that a special command is provided to optimize them. This 


command, called ?DUP ("query-dup") in FORTH-79 and -DUP 
("dash-dup") in FIG-FORTH, duplicates the number on top of the 
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stack, provided that it is not a zero. The previous example can 
now be simplified: 


: COUNTUP2 
?DUP ( FIG-FORTH USES -DUP ) 
IF 1+ 1 
pO: I. 
LOOP 
THEN ; OK 


3 COUNTUP2 2.3 OK 
0 COUNTUP2 


2-4 THE RETURN STACK 


You should now know how to use the parameter stack easily 
with DROP, DUP, SWAP, and so forth. You have also seen how some 
FORTHs make use of a second stack, the “return stack," to keep 
track of DO...LOOP limits and indices. With care, you can also 
make use of the return stack with the FORTH words >R ("to-R"), 
R@ ("R-fetch"), and R> ("R-from"). The command >R removes the 
top item from the parameter stack and pushes it onto the return 
stack. The command R> removes’ the top item from the return 
stack and pushes it onto the parameter. stack. These commands 
should only be used within definitions. For example, one way to 
Swap the second and third item on a parameter stack is: 


: SWAP23 
>R SWAP R> ; OK 
1 2 3 SWAP23 


OK 
- » «3.1.2 OK ( INSTEAD OF 3 2 1 ) 


The command R@ (called R in FIG-FORTH) copies the item on top of 
the return stack and pushes it onto the parameter stack: 


: DOIT 
>R 3 R@ + R> * ; OK 


2 DOIT . 10 OK aaa 


This is useful if you need a number several times ina 
definition but do not want to keep it on top of the parameter 
stack. In many FORTHs, the command R@ is identical to the 
command I, since the loop index is normally kept on top of the 
return stack. Don't forget--if you move a number to the return 
stack with R> and then begin a DO...LOOP (or +LOOP), the number 
will no longer be on top of the return stack. Also remember to 
drop any numbers you push on the return stack before ending a 
definition (using R> DROP as necessary). 
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2-5 EINISHING EARLY 


5.5.1 Leaving a DO...LOOP 


What do you do if you are in the middle of a DO...LOOP and 
decide that you are done? For example, you are searching an 
array for a certain element and have found it. Why should you 
have to continue looking? In fact, you can exit a DO...LOOP at 
any time with the command LEAVE. LEAVE sets the upper limit of 
a loop to its current index (the index is not changed). When 
you reach the end LOOP or +LOOP, you will exit the loop. For 
example: 


: EARLY 100 0 
DOI 5 = 
IF LEAVE 
ELSE I . 
THEN 
LOOP ; OK 


EARLY 0 1 2 3 4 OK 


When I equals 5, you exit the LOOP via LEAVE. 


5-5-2 Exiting a Word 


FORTH-79 also provides for immediately finishing the 
execution of a word with the command EXIT. EXIT is especially 
useful if you encounter a condition while executing a word which 
makes executing the rest of the word pointless. For example, 
you may be deep inside your flow of control structure when you 
detect that you are about to divide by zero. What you would 
like to do is to print an error message and exit the word: 


: CALCULATE 
BEGIN 
oe eCOde.ee 
IF 
eeemMore code... 
ELSE 
IF ( Nl AND N2 ARE NOW ON THE STACK ) 
DUP O= ( DIVIDE BY ZERO? ) 
IF CR ." WRONG! " 
DROP DROP EXIT 
ELSE / 
e- continue... 
THEN 
THEN 
THEN 
UNTIL ; 


Be sure to clear the parameter stack and return stack before you 
EXIT. If you are trying to EXIT from inside a DO...LOOP, you 
must also clear the return stack before EXITing. Since FORTH-79 
does not specify exactly what a DO...LOOP does to the return 
stack, it is always better to LEAVE a DO...LOOP than to EXIT 
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it. 


2-6 CASE Statements 


CASE statements resemble "staircases" of dependent 
IF...ELSE...THEN clauses, such as we have seen in section 
5S ol.2e CASE statements are easier to read than multiple 
IF...ELSE...THEN statements, especially if there are more than 
two dependent clauses. Neither FIG-FORTH nor FORTH-79 has a 
CASE statement, but there has been much interest in CASE 
statements among FORTH programmers. We have selected two types 
of CASE statements, a "keyed" CASE and a "positional" CASE, to 
use in this section. They are fully described in FORTH 
DIMENSIONS, Vol. II, No. 3, 1980, pages 37-40 and page 89. You 
will find their definitions in appendix B. 


2-6.1. A Keyed CASE 


The keyed CASE uses a nested IF...ELSE...THEN structure to 
select a routine to be executed. The structure begins with the 
word CASE and ends with the word ENDCASE. Each dependent clause 
within the CASE begins with a "selector”™ (a number), followed by 
the word OF, and ends with the word ENDOF. If the argument that 
is on the stack when CASE is entered equals one of the 
selectors, the dependent clause of that selector is executed. 
FORTH then skips to the ENDCASE word. If the argument fails to 
match any of the selectors, execution will continue at the first 
FORTH word (if any) following the last ENDOF (sometimes called 
an "otherwise" clause). Here is a simple example: 


: SPELLNUMBER 
CASE 
0 OF ." ZERO " ENDOF 
1 OF ." ONE " ENDOF 
2 OF ." TWO " ENDOF 
-" TOO BIG * 
ENDCASE ; 


Now try SPELLNUMBER: 
0 SPELLNUMBER ZERO OK 
1 SPELLNUMBER 
5 SPELLNUMBER BIG OK 


2-6.2 A Positional Case 


The positional case selects the nth word in a list of FORTH 
words. The list of FORTH words begins with GODO and ends with 
THEN. If the argument on the stack when GODO is executed is 
zero or less, the first word in the list is executed. Execution 
then continues with the first word (if any) following THEN. If 
the argument is a one, the second word is executed, and so 
forth. If there are four words in the list, any argument of 
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three or 
an example: 


ee ef ef e8 08 of 8 of 


greater 


KNXT . 
KNBC . 
KTLA . 
KABC . 
KHJ . 
KTTV . 
KCOP . 


CHANNEL 


N/A KABC N/A KHJ N/A KTTV N/A KCOP N/A THEN 


Now try channel: 


at 3 


O RmWNHEH SO 


CHANNEL 
CHANNEL 
CHANNEL 
CHANNEL 
CHANNEL 
CHANNEL 
CHANNEL 
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will execute the fourth (last) word. 
KNXT " ; OK 
ma * ) oe 
coy oe 
KTTV " ; OK 
KCOP " ; OR 


NO STATION “ ; OK 
GODO N/A N/A KNXT N/A KNBC RTLA 


NO STATION OK 
NO STATION OK 
NO STATION OK 


KNXT OK. 
NO STATION OK 
KNBC OK 


NO STATION OK 
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=e 
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0= 
0< 
0> 


IF 
ELSE 


THEN 


DO 


LOOP 


+LOOP 


TABLE 5.1 
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TABLE 5-1 FLOW OF CONTROL 


STACK 

(nl n2 --> n3) 
(nl n2 --> n3) 
(nl n2 --> t/f) 
(nl n2 --> t/f) 
(nl n2 --> t/f) 


(nl --> t/f) 
(nl --> t/f) 
(nl --> t/f) 
(t/£ --> ) 
(nl n2 -=> ) 
(n <=> ) 

( --> n) 

( --> n) 
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ACTION 

Leaves the bitwise AND of nl and n2. 
Leaves the bitwise OR of nl and n2. 
True if nl is less than n2. 

True if nl is greater than n2. 

True if nl equals n2. 

True if nl equals zero. 

True if nl is less than zero. 


True if nl is one or greater. 
FORTH-79 only. 


Used in a definition in the form 
t/f IF...ELSE...THEN or simply 
t/f IF...THEN. 

If condition is true, the words 
following IF are executed (but 
the words following ELSE are 
skipped). If false, the words 
following ELSE are executed 

(if the ELSE part exists). 


Used in a definition in the form 
DO...LOOP or DO...+LOOP. 

The words within the loop will be 
repeatedly executed (in order) 
until the loop index (initially n2) 
equals or exceeds the loop upper 
limit. If the word LOOP ends the 
the loop, the index will be 
incremented by 1. If the word +LOOP 
ends the loop, the index will be 
incremented by whatever number is 
currently on top of the stack. 

If the increment is negative, +LOOP 
will decrease the index until it is 
less than (or equal, in FORTH-79) 
the limit. 


Used within a DO...LOOP or 
DO...+LOOP. The word I leaves a 
copy of the loop index on the 
Parameter stack. 


Used within a nested DO...LOOP or 
DO...+LOOP. The word J leaves a 
copy of the index of the 
next-outermost loop on the 
parameter stack. 


FLOW OF 


BEGIN 


UNTIL 


WHILE 


REPEAT 


?DUP 
-DUP 


>R 


R@ 


R> 


LEAVE 


EXIT 
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TABLE 53-1 FLOW OF CONTROL (continued) 


STACK 
(€/£ =--> } 
es 22 


(n <--> n (n)) 


(n --> ) 
( --> n) 
( <--> n) 


(FORTH-79 only) 
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ACTION 


Used in a definition in the form 
BEGIN...UNTIL or 
BEGIN...WHILE...REPEAT. 

The words following the BEGIN will 
be repetitively executed (in order) 
and must leave a t/f condition on 
stack. If the loop ends with UNTIL, 
the loop will terminate when 

a true condition is left on the 
stack. If the loop ends with WHILE, 
the loop will terminate when a false 
condition is left and the words 
between WHILE and REPEAT will be 
skipped. Otherwise, the words 
between WHILE and REPEAT will be 
executed and the loop will repeat. 


Duplicates n if it is not zero. 
( -DUP in FIG-FORTH ) 


Transfers n to the return stack. 


Copies the number on top of the 
return stack to the parameter stack. 
( R in FIG-FORTH ) 


Transfers n from the return stack 
to the parameter stack. 


Forces termination of a DO...LOOP 
or a DO...+LOOP by setting the 
upper limit of a loop to its 
current index. The index is 
unchanged. Execution continues 
until the end LOOP or +LOOP. 


Forces termination of a word. 
Should not be used within a 
DO...-LOOP or DO...+LOOP. 
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WORD 
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TABLE 5.1 FLOW OF CONTROL (continued) 


STACK 


ACTION 


(The following words have been added to FORTH. You will find 
their definitions in Appendix B.) 


CASE 
OF 
ENDOF 


ENDCASE 


GODO 
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Used in a definition in the form 
CASE 

selectorl OF wordsl ENDOF 

selector2 OF words2 ENDOF 
otherwise-words 

ENDCASE. 

A selector is an expression leading 
to a number. If the selector equals 
the number n, the words within the 
respective OF...ENDOF will be 
executed, and execution will 
continue following the ENDCASE. 

If no selector matches n, the 
otherwise-words (between the last 
ENDOF and ENDCASE) will be executed. 


Used in a definition in the form 
GODO word0 wordl ... wordmax THEN. 
The nth word between GODO and THEN 
will be executed. Execution will 
then continue after the THEN. 

If n is 0, word0O will be executed. 
If n is 1, wordl will be executed 
and so on. If n is less than 0, 
word0 will be executed; if greater 
than the final word (wordmax), the 
final word will be executed. 
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CHAPTER 6 


* * 
* * 
* * 
* THE EDITOR * 
* and * 
* MASS STORAGE * 
* * 
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FORTH words which you create from the _ keyboard are 
immediately compiled into the dictionary. The carefully typed 
lines that went into their creation are now gone forever. There 
is no way to reconstruct these lines (called the "source" code) 
from the word which is now part of the dictionary (called the 
"compiled" or "object" code). FORTH dictionaries are made from 
compiled code. Fortunately, FORTH provides a means of saving 
and altering source code for future use called the "editor" (see 
below). Furthermore, useful programs generate useful data, 
which you may also want to save for future use. In fact, FORTH 
lets you save all three: source code, dictionaries, and data. 


As your programs and data increase in size, you would soon 
overrun your available computer memory. Because of this, you 
must make of use of external "mass" storage, such as ae floppy 
disk or cassette tape. Mass storage is generally much larger 
than computer memory, and it is relatively inexpensive. So 
before you can begin a FORTH programming session, you must read 
in the current FORTH dictionary from the mass storage device 
where it is stored. When you finish a session, you can usually 
save the new FORTH dictionary in mass storage for future use 
(see chapter 4). 


Because mass storage is larger than the available computer 
memory space, you can only read or write a small part of mass 
storage at a time. These units of mass storage are called 
"blocks" if they hold object code or data and "screens" if they 
hold source code. In FORTH-79, blocks and screens are 
identical. Their names serve only to indicate how they should 
be used: programs save "blocks" of data while the editor edits 
"screens." In FIG-FORTH, however, blocks are usually smaller 
than screens. 


In FORTH-79, each block of mass storage can hold 1024 bytes 
of data. If the block is used as a screen, these 1024 bytes 
will usually be organized as 16 lines of 64 characters each (16 
x 64 = 1024). Some terminals, however, require 24 lines of 40 
characters (960 bytes), with 64 inaccessible characters in each 
screen. A single 5 1/4-inch, 16-sector, floppy diskette holds 
about 140 blocks/screens. 


In FIG-FORTH, the constant B/BUF tells you how many bytes 
there are in each block (there is one block to a buffer--more on 
this later). B/BUF is usually some multiple of 128 bytes. It 
may take several blocks to make one screen. If you are _ using 


6.0 


THE EDITOR & MASS STORAGE 58 


FORTH-79, you can define B/BUF as follows: 
1024 CONSTANT B/BUF OK 


Blocks/screens are read into special areas in memory called 
"buffers." Buffers will be discussed later in this chapter. For 
now, Please read the following warning: 


KRKEKEKEEKEKKEKEKEKEKKEKEEKEEKEKKEEKEEKEEKEEKEKKEKEE 


Pa 


ed It is a good idea to begin every FORTH * 
* programming session with the command * 
* * 
* EMPTY-BUFFERS OK % 
* 

KEKKEEEKEEEKKEEKEKKEKREEKEEEEKKEKEEKKKKKKKKKKKK 


This is because at the beginning of a session, the buffers are 
filled with garbage which could be accidently written into mass 
storage. (Note: In MicroMotion FORTH, the EMPTY-BUFFERS is done 
for you.) 


6.1 THE EDITOR 


Programming (with FORTH) is never a one-shot operation. 
Inevitably you will want to add or change something later as you 
think about your work a second time or devise a new purpose for 
your program. To keep you from having to type the entire 
program again, FORTH includes a separate program called the 
editor. The editor lets you type commands and definitions into 
the mass storage screen of your choice. Nothing you type takes 
effect until you give the go-ahead. By using the editor, you 
can add, delete, and move any element in your program easily and 
quickly. The editor allows you to experiment without 
jeopardizing the work you've already done. 


Programs created with the editor can occupy many screens, 
but you can only edit one screen at a time. It is up to you’ to 
decide which screens a program will occupy. Programs which span 
more than one screen should be on consecutive screens. Editing 
commands vary from FORTH to FORTH. You should consult someone 
familiar with your FORTH to learn how to use your editor (see 
chapter 1, Getting Started). (If you have purchased MicroMotion 
FORTH, you should now turn to appendix F to learn how to invoke, 
use, and exit the editor.) 


6-2 LISTING SCREENS 
If you want to look at a screen but have no intention of 
changing anything on it, you can "list" the screen on an output 
device such as a printer with the word LIST. For example, to 
LIST screen 50, type: 


50 LIST OK 
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The screen will be listed, but you will not have access to the 
editing commands. If you look at the screen and decide that you 
do want to make changes after all, simply invoke the editor and 
edit the screen. 


6.3 USING A SCREEN 


When you are finished editing a program and wish to compile 
it into the dictionary, use the command LOAD. Again, simply 
type the number of the screen you wish compiled and the word 
LOAD: 


50 LOAD OK 


FORTH will now compile screen 50 exactly as if you were typing 
it in from the keyboard. Words will be defined, variables and 
constants created, and commands executed as they are encountered 
on the screen. If there is an error, you can forget the 
erroneous word, reedit the screen, and LOAD it again. By the 
way, you can be very liberal with comments when you type a 
definition on a_e screen. The comments do not occupy any 
dictionary space when you later LOAD the definition. 


6.4 USING CONSECUTIVE SCREENS 


The definitions you type may vary greatly in length. Some 
will be grouped together on a single screen; others may _ span 
several screens. Some FORTHs include a command to let you LOAD 
a range of screens: 


50 65 THRU 


will LOAD screens 50 through 65, inclusive. If you are using 
FIG-FORTH, you can put the command --> at the end of a screen to 
LOAD the next screen. 


The FIG-FORTH word ;S ("semi-s"), on the other hand, will 
keep definitions on the same screen from being compiled 
together. The compilation will stop at the first ;S on the 
screen. This can be particularly useful with multiple 
definitions, each of which depends on the preceeding 
definition. If there is an error in the first one, you need to 
know about it and fix it before trying the rest of them. Using 
a ;S command after the first definition will allow you to test 
this first definition independently. 


6.5 BUFFER MANAGEMENT 


Mass storage is a practical necessity. It can hold far 
more information than the computer's memory can at far less 
cost. This information must be divided into manageable chunks 
for use in memory, however. As you have seen above, each chunk 
is called a block and holds B/BUF bytes or characters. Because 
so many programs take more room than this, however, one block in 
memory at a time is often not enough. A compromise is to have 
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several block storage areas (called "buffers") in memory, each 
of which holds one block. You might call blocks 70 through 73 
into memory, for example, to work with a program which occupies 
all four of them. Each would be in a separate buffer while in 
memory, however, and would keep its separate identity. 


When you first call for a block, a copy of the block on the 
mass storage device is read into a buffer. If you make any 
changes, this block must be recopied bac{ onto the mass! 
storage device for permanent storage. FORTH now has the problem 
of getting the blocks from the mass storage device, deciding 
which buffers to copy them into, checking each one to see if any 
changes have been made, and recopying altered blocks back onto 
the mass storage device. These are problems of "buffer 
management.” 


Consider what FORTH must do when you invoke a block (in 
this case, number 12) for editing. First it searches the 
buffers to see if block 12 is already there. If it is, then 
editing can proceed. If it isn't, then FORTH searches for a 
buffer to use. Perhaps all buffers are occupied. One will have 
to be sacrificed, then. If this block has not been changed 
Since being copied into a buffer, then nothing is lost by 
destroying it and using the space for block 12. If changes have 
been made, then FORTH must find a way to save these changes. In 
this situation, FORTH must recopy the block onto the mass 
storage device before filling the buffer with block 12. 
Fortunately, FORTH handles all this for you automatically. 


6.6 BUFFER COMMANDS 


Good buffer management minimizes the number of 
blocks/screens read from or written to mass storage. For this 
reason, blocks are not moved from buffers to mass storage unless 
the buffers are needed for newer blocks. If you edit or 
otherwise change a block in a memory buffer and then terminate 
your session (turn off your computer), these changes will be 
lost. To ensure that all necessary blocks are rewritten into 
mass storage, use the command SAVE-BUFFERS (called FLUSH in 
FIG-FORTH). When using SAVE-BUFFERS, it is not necessary to 
specify which blocks or screens are being saved. 


The command EMPTY-BUFFERS, in contrast, will erase whatever 
is in the buffers currently. As you boot up FORTH,’ stray 
characters may appear in the buffers. FORTH may interpret these 
as normal blocks and accidentally recopy them onto the disk at 
some point, damaging the blocks that are already there. Typing 
EMPTY-BUFFERS at the beginning of a session with FORTH will 
guard against such damage. 


Finally, before you change tapes or disks, you should type 
SAVE-BUFFERS followed by EMPTY-BUFFERS. The SAVE-BUFFERS 
ensures that all altered blocks are recopied onto the old tape 
or disk. The EMPTY-BUFFERS ensures that a block requested from 
the new tape or disk will not still be in the buffers from the 
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old tape or disk. In addition, if you see a message such as 


DISK ERROR ( Example: no disk in the drive or data error ) 
RANGE ERROR ( Example: block number is too large ) 


type the following commands: 


SAVE-BUFFERS 
EMPTY-BUFFERS 


The SAVE-BUFFERS command will recopy only those buffers that you 
have deliberately changed, ignoring those in a confused state, 
and EMPTY-BUFFERS will clear out the buffers so that you can 
start over. 


6-2 BLOCKS 


Blocks generally hold data and would be meaningless if 
viewed through the editor. However, you can write your own 
FORTH words to move data to and from mass storage blocks. 
Copying a block into a buffer is done with the command BLOCK: 


50 BLOCK OK 


As usual, the buffers are searched for block number 50. If 
necessary, a buffer is freed and block 50 is copied from mass 
storage into the buffer. The address in memory of the selected 
buffer (and therefore of the first byte in the block) is now on 
the stack. This address is effectively the starting address of 
an array containing the B/BUF bytes in block 50. You can use 
any of the array commands you learned in chapter 3 to manipulate 
this array. For example: 


50 BLOCK . 14168 OK 


Block 50 is now an array beginning at address 14168 (or some 
other address). If you want to store a three at the 100th byte 
of block 50, type: 


50 BLOCK OK 
3 SWAP 100 + ! OK 


Or you could combine the two operations: 
3 50 BLOCK 100 + ! OK 
To tell FORTH that a block has been altered and needs to be 
recopied into mass storage at some point, use the command 
UPDATE. UPDATE marks the last block searched for as an altered 
block. To ensure that the block you wish to update is the last 
one searched for, request it yourself: 


50 BLOCK DROP UPDATE OK. 
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Remember how buffer management works. If block 50 is already in 
memory, FORTH will not attempt to copy it into a buffer. 
Therefore, you will not lose the changes you have already made 
in block 50. Even so, FORTH will count block 50 as the last one 
searched for, making it eligible for UPDATE. If you do not 
UPDATE a block, any changes you make to it will be lost. (The 
MicroMotion editor UPDATEs screens as they are altered.) 


6.8 DATA SPANNING SEVERAL BLOCKS 


Often you will need to store more data than can comfortably 
fit in memory. For example, you may need to record the 
magnitude of several thousand heart beats. This much data will 
require many blocks of mass storage, which will be brought into 
buffers as needed, in no particular order. But your programs 
would be easier to write if you could somehow make adjacent 
blocks look like adjacent elements in a large array. You can do 
this with careful use of the command BLOCK. For example, 
Suppose the magnitude of each heartbeat occupies one byte of 
memory; you determine that the 1090th heart beat has a magnitude 
of 57. Furthermore, you decide to store heart beats on _ blocks 
50 to 59 on your mass storage device. If each block holds 1024 
bytes, the 1090th byte will be the 66th byte of the 51st block. 
In fact the sequence B/BUF /MOD gives you both the byte offset 
and the block offset (the number of blocks away from 50). 
Adding the block offset to the starting block (50) gives you the 
block containing your data. These operations can now be 
combined into a FORTH word: 


50 CONSTANT STARTHEART 


: HEARTBEAT ( #HEARTBEAT --> MEMORY-ADDRESS ) 
B/BUF /MOD STARTHEART + BLOCK UPDATE + ; 


Notice the use of UPDATE which ensures that the recorded 
heartbeats will be rewritten at some point into mass storage. 
Notice also the use of the constant STARTHEART, which makes it 
easier to remember (and change) the starting data block. 


HEARTBEAT is now, to all appearances, a CARRAY of 10240 
(10K) bytes (see chapter 3). Specifying a heart beat will leave 
its address on the stack. Changing the 3090th heart beat to 57 
is now simply a matter of typing: 


57 3090 HEARTBEAT ! OK 


Don't forget to save your heartbeats with a SAVE-BUFFERS before 
terminating your session (turning off your computer). 


The FORTH you are using may also have many other mass 
storage commands to index blocks by contents, back-up selected 
blocks, and so. forth. (For a list of the disk utilities 
Supported by MicroMotion FORTH, see appendix J.) 


DATA SPANNING SEVERAL BLOCKS 6.8 


THE EDITOR & MASS STORAGE 


63 


TABLE 6.1 BLOCK AND SCREEN COMMANDS 


WORD STACK 
B/BUF (<--> n ) 


LIST (n-screen --> ) 
LOAD (n-screen --> ) 
THRU ( nl n2 --- ) 
~=> ( --> ) 

7S ( --> ) 


UPDATE ( <--> ) 


SAVE-BUFFERS ( --> ) 


EMPTY-BUFFERS ( --> ) 


BLOCK (n-block 
--> address) 


ACTION 


Pushes the number of bytes per 
disk buffer on the stack. 


Lists the ASCII contents of screen 
n-screen on the output device. 


Begins interpretation of screen 
n-screen. The contents of this 
are interpreted as if typed from 
the keyboard. Control then returns 
to wherever the LOAD was initially 


typed. 


LOADs consecutive screens, starting 
with screen nl and ending with n2. 


Continues LOADing the next screen. 
(FIG-FORTH only) ("next screen") 


Stops interpreting this screen. 
(FIG-FORTH only) ("semi-s") 


Marks the most recently referenced 
block as modified. 


Writes all UPDATEd blocks into 
mass storage. 


Erases all blocks from memory. 


Leaves the address of the first 
byte of block n-block. This is 
actually the address of the memory 
buffer currently containing block 
n-block. 
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CHAPTER 7 


* * 
* * 
* MORE ABOUT NUMBERS i 
* * 
* * 
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So far we have been working with the familiar decimal (base 
10) number system. In the decimal system, each digit in a 
number can have one of ten values: 01234567 8or 9. This 
system seems natural to us. After all, we each have ten fingers 
(and toes). When you first begin a_ session with the FORTH 
language, the numeric base is initialized to decimal. You can 
return to decimal at any time with the word DECIMAL. Computers, 
however, have essentially one finger (or toe) each and count in 
the binary (base 2) system. In this system, each digit can have 
one of two possible values: 0 or l. 


2-1 THE BINARY SYSTEM 


FORTH keeps the current numeric base in the system variable 
BASE. You can define the word BINARY to change to the binary 
system this way: 


DECIMAL 

: BINARY ( CHANGE TO BASE 2 ) 
2 BASE ! ; OK 

BINARY OK 


Now try putting a 15 on the stack: 
15.27 15 


FORTH refuses to accept this number since it contains a digit 
(5) which is neither a zero nor a one. Now try: 


ix # 5.30 OF 


What happened? You created a number that was one larger’ than 
the largest digit. In the DECIMAL system, you would say that l 
plus 9 is “zero, carry the one" to make 10 (pronounced "“ten"). 
In the BINARY system, you should say that 1 plus 1 is "zero, 
carry the one" to make 10 (pronounced "one zero"). 


You can type numbers in one number system and print them in 
another: 


BINARY 10 DECIMAL . 


DECIMAL 255 BINARY . 111111)) OK 
DECIMAL OK 
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You are left in whatever number system you typed last (in this 
case, DECIMAL). It is a good idea to finish in DECIMAL whenever 
possible. 


Each zero or one in computer memory is called a "bit" or is 
said to contain one "bit" of information. But, practically 
speaking, working with individual bits is both tedious and 
confusing. Instead, computer memory is organized into groups of 
eight bits called "bytes" of information. Each byte in memory 
has a location or "address." You can think of each byte as a 
cubbyhole or post office box containing eight zeroes or ones. 
But please don't confuse the address of a byte with its 
contents. The byte at address 27 could contain the number 15. 


2-2 HEXADECIMAL NUMBERS 


The hexadecimal (base 16) number system (usually 
abbreviated "hex") lets you work with groups of four zeroes or 
ones. Each of the 16 possible groups corresponds to a single 
hexadecimal digit: 


HEX BINARY DECIMAL HEX DECIMAL 
0 0000 0 8 1000 8 

i. 0001 1 9 1001 9 

2 0010 2 A 1010 10 

3 0011 3 B 1011 ll 

4 0100 4 Cc 1100 12 

5 0101 5 D 1101 13 

6 0110 6 E 1110 14 

7 0111 7 F 1111 15 


The word HEX lets you work in the hexadecimal system: 


DECIMAL 
: HEX ( BASE 16 ) 
16 BASE ! ; OK 


The contents of any byte can be represented by eight binary or 
two hexadecimal digits: 


BINARY 01101110 HEX . - OK 
HEX 4F BINARY . 1001111 OK 


DECIMAL OK 


Hex numbers are more readable if you precede them with an extra 
zero: OAB instead of just AB. 


2-3 BYTES AND WORDS 


How many different patterns of eight bits can you store in 
each byte? Well, the smallest pattern you can store is BINARY 
00000000 (DECIMAL 0). The largest pattern you can _ store is 
BINARY 11111111 (DECIMAL 255). So you can store any DECIMAL 
integer from 0 to 255 in any byte. This makes 256 possible 
patterns. Each pattern can represent a DECIMAL integer, but it 
can also represent almost anything else. For example, the 
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BINARY pattern 01000001 can mean capital 'A' or even "don't 
forget to see your dentist tomorrow." As long as everyone agrees 
what each pattern means in a given situation, there will be no 
confusion. 


Since 256 possible patterns just aren't enough, two 
adjacent bytes are usually combined into one 16-bit memory 
"cell." One of the two byte addresses, usually the lower one, is 
chosen to be the address of the memory cell. The rightmost 
eight bits are called the "least significant byte" and are 
usually found at the lower or cell address. The leftmost eight 
bits are called the "most significant byte." 


A 16-bit memory cell can hold one of 65536 possible 
patterns. The meaning of each pattern depends on the context in 
which it is used. For example, in some situations, the contents 
of one 16-bit cell represent the address of another 16-bit cell 
(or 8-bit byte). This gives you a possible address range from 0 
to 65535. Since many microcomputers use 16-bit addresses, they 
are limited to 65536 bytes of usable memory and are said to have 
a "65K address space." By the way, 10 bits of memory can hold 
1024 different patterns: 


BINARY 1111111111 DECIMAL . 1023 OK 


The number 1024 is so close to 1000 that it is usually called 
"1K." You will often find that 65536 bytes of memory are simply 
called "64K" of memory. 


1.4 SIGNED INTEGERS 


Another way of interpreting the 65536 possible 16-bit 
patterns is to divide them into half positive and half negative 
integers. If the furthest bit to the left (the "most 
Significant bit" or MSB) is zero, then the remaining 15 bits are 
interpreted as positive integers. If the MSB is one, the 
numbers are negative integers. The largest possible positive 
integer is then: 


BINARY 0111111111111111 DECIMAL . 32767 OK 


which is also called "32K." To form negative integers, we can 
subtract positive integers from zero: 


DECIMAL 0 1 — . =] OK 
BINARY 1327212) 7747 DECIMAL . -1l OK 


Notice that a 16-bit number with all "ones" is interpreted as 
the negative integer "-1." Why? Well, if we add -l to +1 we will 
get the number zero. More precisely, we will get a number with 
16 zeroes and a 17th one, which is thrown away: 


BINARY 1111111111111111 1 + . 0 OK 
DECIMAL OK siete 
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What happens if you try to create a positive integer larger 
than 32767? 


32767 1 + . =32768 OK 
-32768 BINARY . -1000000000000000 OK 
DECIMAL OK eee 


Any 16-bit number larger than 32767 will have a MSB of one _ and 
will be treated as a negative number. In fact, by adding one to 
the largest positive number (32767), we have "wrapped around" 
within the number space to the largest negative number 
(-32768). In some FORTHs, this "wraparound" is treated as an 
"arithmetic overflow" error. In most FORTHS, however, 
wraparound is treated as the normal consequence of having 16-bit 
"signed" integers and is not considered to be an error. 


Numbers pushed onto the FORTH stack are normally 
interpreted as 16-bit signed integers, also called 
"single-number integers," which range from -32768 to +32767. 
Many FORTHs actually allow you to enter much larger numbers but 


discard all but the lowest 16 bits. This can lead to some 
surprising results: 


100000 . -31072 OK 


Also surprising are the results of arithmetic calculations 
producing intermediate values of more than 16 signed bits: 


30000 10 * 10 / . -2768 OK 


27-5 RATIONAL ARITHMETIC 
Many operations with numbers’ require multiplication by 
fractions or ratios. In other words, these operations can be 
done as a multiplication followed by a division. For example, 
to find 2/3 of 1000, you can type 
1000 2 * 3 / . 666 OK 


To multiply 20 by pi to two decimal digits of accuracy (3.14), 
try 


20 314 * 100 / . 62 OK 
For greater accuracy (3.1415) try 
20 31415 * 10000 / . =2 OK 


What happened? The intermediate product of 20 * 31415 was 
larger than 16 signed bits, and the extra bits were discarded. 


To protect these intermediate products, you can use the 
FORTH operator */ ("times-divide") : 


20 31415 10000 */ . 62 OK 
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This operator forms the product of the first two numbers and 
divides it by the third number. But the intermediate product is 
treated as a signed 32-bit ("double-number") integer. This 
double-number product is divided by the single-number divisor to 
yield a single-number answer. The */ operator is especially 
useful in conversions, such as "feet to meters," "Fahrenheit to 
Centigrade," and so forth. By using */ you are guaranteed that 
your calculations will be fully accurate, as long as the final 
result does not exceed the limits of a single-number integer. 


FORTH also provides the operator * /MOD 
oe which combines the function of * and 
MOD: 


30000 4 9 */MOD OK 


This operator multiplies the second and third stack items to 
form a double-number intermediate product (30000 4 * yields 
120000). A /MOD is then done between the intermediate product 
and the number on top of the stack to leave the single-number 
remainder (second item) and quotient (top item) on the stack 
(120000 9 /MOD): 


« #13333 3. O8 


2-6 DOUBLE NUMBERS 


Sometimes even single-number results are too small. For 
example, if you want to keep track of a checking account in 
pennies, you would be limited to amounts no larger’ than 
$327.67. Because of this, most FORTHs provide "double-number" 
32-bit signed integer numbers and operators. A few 
double-number words (D+ D< and DNEGATE) are included in the 
FORTH-79 standard. The remaining double-number’ words are 
considered to be a language extension, and you may have to LOAD 
them into your dictionary from mass_ storage. See chapter 1 
(Getting Started) and chapter 6 (The Editor and Mass Storage) 
for details. You may now put up to $21474836.54 into your 
checking account. 


The format of double numbers varies from FORTH to FORTH. 
In MicroMotion FORTH, for example, any number ending with a 
decimal point is considered to be a double number. To print the 
double number on the stack, use the word D. as follows: 


200000. OK 
D. 200000 OK 


FORTH actually splits the double number into two. single 
numbers: the most significant number is kept on the stack above 
the least significant number: 


HEX OK 
02 468KC. CR. . 
68AC OK 


DECIMAL OK 
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This suggests that a single-number integer can be increased to a 
double-number integer by pushing a second number over it on the 
stack. Positive numbers can be extended by pushing a zero; 
negative numbers by pushing a -1. Consider the definition of 
the word S->D (single to double-number) : 


: S=->D 
DUP O0< IF -1 ELSE 0 THEN ; OK 


123 S->D D. OK 
-49 S->D >. Ae or 


To convert a double number to a single number, simply DROP off 
the most significant part: 


4. DROP . 4 OK 


Of course, if the double number doesn't fit the single~-number 
format, the extra bits will be lost. 


Most of the single-number arithmetic and stack words have a 
double-number equivalent. For example, 2DROP drops a double 
number from the stack. These double-number words are briefly 
described in table 7.1. The double-number stack operators can 
also be used to manipulate single-number numbers two at a_ time. 
Double-number intermediate results are possible, however, by 
using mixed-number words (see above). 


2-2 UNSIGNED INTEGERS 


Sometimes it is better to use a number as a 16-bit unsigned 
number (ranging from 0 to 65535) rather than a 16-bit signed 
number (ranging from -32768 to +32767). For example, you may 
need to check if one address in memory is lower than another: 


HEX OK 
36F9 7AAB < . 1 OK ( TRUE ) 


but 


7AAB 9072 < . 0 OK ( FALSE! ) 
DECIMAL OK "~ 


The hexadecimal number 9072 is treated as a negative number by 
the signed comparator <. FORTH-79 provides a handful of 
arithmetic words ( U* U< and U.) which treat numbers as 
unsigned 16-bit numbers. FORTH also provides an_ unsigned 
mixed-number word U/MOD (called M/MOD in FIG-FORTH) and an 
extended unsigned double-number word DU<. These words are 
briefly described in table 7.2. Try the above comparison again 
with the unsigned comparator U<: 


HEX OK 
7AAB 9072 U< . 1_OK ( TRUE ) 
DECIMAL OK - 
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Note: in FIG-FORTH, U/MOD is simply called U/, although it 
functions as an unsigned /MOD. 


2-8 MORE MIXED-NUMBER OPERATORS 


You may have noticed that most FORTHs provides no 
double-number multiplication command. This would lead to 
double-double-number results, which would be difficult to use. 
FIG-FORTH, however, provides two mixed-number words, M* and M/, 
which allow you to obtain doubl e-number results from 
mixed-number arithmetic. It is also possible to define these 
words in FORTH-79 (see appendix B). 


The word M* multiplies two signed single-number integers to 
form a signed double-number product: 


1000 1000 M* D. 1000000 OK 
The word M/ divides a signed double-number divisor by a_ signed 
Single-number dividend to produce two signed single-number 
results: the quotient (on top of the stack) and the remainder 
(underneath it). The remainder takes its sign from the 
dividend: 


1000000. 1000 M/ . . 1000 0 OK 
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TABLE 7.1 DOUBLE-NUMBER WORDS 


WORD STACK 
D+ (dl d2--> d-sum) 
DABS (dl --> ud2) 
DNEGATE (dl --> d2) 
D. (dl --> ) 
D.R (dl n-width -->) 
D- (dl d2-->d-diff) 
DO= (dl --> t/f) 
D= (dl d2--> t/f) 
DMIN (dl d2--> d-min) 
DMAX (dl d2--> d-max) 
DU< (udl ud2--> t/f) 
2! (dn address -->) 
2@ (address--> dn) 
2DROP (dn --> ) 
2DUP (dl --> dl dl) 
20VER (dl d2 

--> dl d2 dl) 
2ROT (dl d2 d3 

--> d2 d3 dl) 
2 SWAP (dl d2-->d2 dl) 


2CONSTANT and 
2VARIABLE 


ACTION 

Adds dl to d2. 

Forms the absolute value of dl. 
Reverses the sign of dl. 

Prints a double number. 
(FIG-FORTH only.) 

Prints a double number 
right-aligned in a field of 
n-width characters. 

Subtracts dl from d2. 

True if dl equals zero. 

True if dl equals d2. 

Leaves the smaller of dl or d2. 


Leaves the larger of dl or d2. 


True if the unsigned dl is less 
than the unsigned d2. 


Stores dn at the address. 

Fetches dn from the address. 

Drops dn from the stack. 
Duplicates dl on the stack. 

Leaves a copy of the second double 
number on the stack. 

ROTates the third double number 

to the top of the stack. 

SWAPs dl and d2. 


The double-number equivalents of 
CONSTANT and VARIABLE. 
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TABLE 72.2 MORE ARITHMETIC WORDS 


WORD STACK ACTION 
DECIMAL Sets the FORTH number base to 10. 
*/ (nl n2 n3-->n4) Multiplies nl by n2, then divides by 


n3. The intermediate result of the 
multiplication is a double number. 


* /MOD (nl n2 n3 Multiplies nl by n2, 
-->n4 n5 ) then does a /MOD 
by n3. The intermediate result of 
the multiplication is a 
double number. 


U* (unl un2-->un3) Unsigned multiplication 
of unl by un2. 
U< (unl un2--> t/f) True if unsigned unl is less than 
un2. 
U. (unl --> ) Prints an unsigned number. 
U/MOD (udl un2 Performs the unsigned division of 
-->un3 un4) double number udl by 


Single number un2, leaving the 

single-number remainder un3 and 

Single-number quotient un4. 
M/MOD (Called M/MOD in FIG-FORTH.) 


(The following numbers have been added to FORTH-79. You will 
find their definitions in appendix B.) 


M* (nl n2-->d-prod) Multiplies nl by n2, leaving a 
double-number product. 


M/ (dnl n2-->n3 n4) Divides double number dnl by 
single number n2, leaving 
single-number remainder n3 and 
Single-number quotient n4. 
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Strings are simply sequences of characters, such as_ the 
letters in this sentence. Strings are useful for printing 
messages, accepting specific instructions from the user, and _ so 
forth. You have already learned how to use numbers and how to 
store them in variables. This chapter will show you how to use 
strings and how to store them in string variables. 


Neither the FORTH-79 standard nor FIG-FORTH specifies what 
strings are or how they should be handled. This is because FORTH 
is so extensible that there are many ways to implement strings, 
so the choice is left up to the programmer. This chapter 
describes the string commands written for MicroMotion FORTH-79. 
The definitions for these words are given in appendix B. Before 
reading further, you should make sure that these string words 
have already been added to your FORTH. See chapter 1.0 (Getting 
Started) and appendix A.3 for details. 


8.1 STRING VARIABLES AND LITERALS 


Strings have three basic properties: a sequence of 
characters, a current length (which may be zero), and a maximum 
length. When you move strings from one location (the source 
string) to another (the target string), the current length of 
the source string tells how many characters to move. You set 
the maximum length of the target string to make sure that the 
source string fits the target. 


String commands frequently require string arguments or 
leave string results on the stack. Instead of pushing all of 
the characters in a string onto the stack, it is only necessary 
to push the starting address and current length of the string 
onto the stack. In other words, one "string argument" means two 
arguments on the stack: the starting address of the string and 
the current length of this string. As an example, the _ string 
command LEN replaces any string argument on top of the stack 
with the current length of that string: 


( n-start-adr n-cur-len --> n-cur-len ) 
or simply 
( string --> n-cur-len ) 

In fact, the definition of LEN is trivial: 


: LEN SWAP DROP ; 
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You can create a string variable with the command STRING: 
10 STRING ALPHA OK 
ALPHA is now a string variable with a maximum length of ten 


characters. The parameter field of the word ALPHA looks like 
this: 


ALPHA starting address of chars 
/ / 

Max Current Space for 10 characters 
length length 

+0 +1 +2 


Whenever ALPHA is executed, the starting address of the 
character sequence and its current length are pushed on the 
stack. As you can see from the diagram above, it is possible to 
find ALPHA's maximum length, given the starting address of the 
character sequence. In fact, the command MLEN, which replaces a 
string argument with its maximum length, is defined as: 


: MLEN DROP 2- C@ ; 
Now try LEN and MLEN on ALPHA: 


ALPHA LEN . 
ALPHA MLEN . 10 OK 


Notice that ALPHA has a current length of zero. In other words, 
ALPHA, like all strings created by STRING, is initialized to be 
a "null string." The maximum length of ALPHA is 10, as you might 
expect. In fact, STRING will limit the maximum length of any 
String variable to 255. The minimum length of a string variable 
will be one. 


A string constant or string "literal" is created with the 
command " ("quote"). The string is terminated by a second " . 
Because " is itself a FORTH word, a blank must separate it from 
the following string. This blank is not included in the 
string. Furthermore, there must be at least one character in 
the sequence (see also NULLS below). For example, to create the 
string "ABC," type: 


n ABC" 


When the " is executed, either directly from the keyboard or 
inside of a definition, the usual string arguments, starting 
address and current length, are pushed on the stack. A string 
literal is created in a temporary holding area and, as a result, 
has no maximum length. In fact, all string literals should be 
used immediately before the temporary holding area is accidently 
reused. Only string variables can be used as the target for 
String operations. String literals are only used for source 
strings. 
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The command S! ("s-store") stores a source string into a 
target variable: 


" ABC" ALPHA S! OK 


ALPHA now contains the string "ABC." The current length of ALPHA 
is now three: 


ALPHA LEN . 3 OK 


You can use the FORTH command TYPE to type a string on your 
terminal: 


ALPHA TYPE ABCOK 
" HEY! " TYPE HEY! OK 


TYPE needs only the starting address and current length of the 
string. Notice that the "quotes" in the literal string " HEY! " 
are not part of the string. Notice also that TYPE will not add 
a blank at the end of a string (ABC OK) unless it appears in the 
String (HEY! OK). Here are some more examples: 


20 STRING BETA OK 

" THE ANSWER IS © BETA S! OK 
CR BETA TYPE 

THE ANSWER IS OK 

CR BETA TYPE ALPHA TYPE 

THE ANSWER IS ABC OK 

CR BETA TYPE ALPHA TYPE " " ( 2 BLANKS ) TYPE 
THE ANSWER IS ABC 

CR BETA TYPE ALPHA TYPE SPACE 
THE ANSWER IS ABC OK 

ALPHA BETA S! 

BETA TYPE ABC OK 


Notice the use of SPACE to print a blank space on your 
terminal. The command S! will limit the source string length to 
the maximum length of the target: 


4 STRING SHORT 
" THIS IS A LONG STRING" SHORT S! OK 
SHORT TYPE THISOK 


If you wish to clear a string variable to its original 
"null-string" state, simply use S! with the source string NULLS 
like this: 

NULL$ ALPHA S! OK 
ALPHA TYPE OK 
ALPHA LEN ._0 OK 


You cannot create a "null-string" literal, since each string 
literal must contain at least one character. 
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8.2 SUBSTRINGS 


Sometimes you may wish to examine or change a part of a 
larger string, called a "substring." Substrings may be selected 
with the commands MID$ , RIGHTS , and LEFT$. Substrings may be 
altered with the command SUB! . 


8.2.1 Selecting Substrings 


The command MID$ needs to know the source string, the 
Starting offset of the substring you want to examine, and the 
length of the substring. Offsets within a string always. start 
at offset number one. MID$ does not create a new string. 
Instead, it replaces its arguments with the starting address and 
current length of the substring. The results of MID$ appear to 
be a new string, which can then be used as an argument to other 
string words. MIDS$ produces source strings only! If you need 
to change a substring, see SUB! below. Here are some examples 
of MIDS: 


" THIS IS A STRING!" BETA S! OK 
BETA 1 8 MID$ OK 

CR TYPE 

THIS IS OK 

CR BETA 9 9 MID$ TYPE 
A_STRING!IOK 

“CR BETA 9 100 MIDS TYPE 
A_STRING!OK 
CR BETA 100 100 MIDS TYPE 
! OK 

CR BETA -10 8 MIDS TYPE 
THIS IS OK 


The result of MID$ (a substring) is used as the argument of 
TYPE. If the starting position or length lie outside of the 
source string, MID$ will "clip" them so that at least one 
character appears in the _ substring. MID$ always returns a 
substring of at least one character. 


RIGHTS and LEFT$ are simply special cases of MIDS. They 
require only two arguments: the source string and the substring 
length. RIGHTS returns a substring of the given length of the 
rightmost characters of the given string. Conversely, LEFT$ 
returns a substring of the given length of the leftmost 
characters of the given string. A few examples should make this 
Clear: 


" LETS TRY AGAIN " BETA S! OK 
CR BETA 6 RIGHTS TYPE 

AGAIN OK 

"CR BETA 9 LEFT$ TYPE 

LETS TRY OK 


LEFT$ and RIGHTS, like MID$, always return a substring with at 
least one character. 


SUBSTRINGS 8.2 


STRINGS 77 


8.2.2 Changing Substrings 


Once a substring has been selected by LEFT$ , MID$ , or 
RIGHT$ , it can be altered by SUB! . SUB! stores a source 
string into a target substring without changing the current 
length of the target substring. The action of SUB! will be 
limited to the current length of either the source string or the 
target substring, whichever is least: 


BETA CR TYPE 


LETS TRY aan OK 
BETA 6 3 MIDS CR TYPE 


TRY OK 

SEE" BETA 6 3 MID$ SUB! OK 
BETA CR TYPE 

ETS SEE AGAIN OK 


RUN D ETA 6 3 MID$ SUB! OK 
BETA CR TYPE 
AGAIN OK 


Incorrect selection of the target substring can cause SUB! to 
write over FORTH code and destroy your dictionary. For this 
reason, you should always create your substring with LEFTS$S , 
MID$ , or RIGHTS , and you should use SUB! as soon as possible. 


8.3 STRING COMPARISONS 


8.3.1 String Equality 


Two strings are considered equal if they have identical 
character sequences and the same current length. You can test 
for equality with the word S= as follows: 


ABC" ALPHA S! OK 


ABC" ALPHA S= 0 
ABS" ALPHA S= . OK 
ABC " ALPHA S= . OK 


NULL$ ALPHA S! OK 
NULL$ ALPHA S=. 1 OK 


Notice that two null strings will always match. Now consider: 
* CAT" * DOG" S= . 1 OK 


What happened? Since all string literals are created in the 
same temporary location, the string "DOG" replaced the string 
"CAT." The command S= subsequently compared "DOG" with "DOG" and 
found them equal! 


A string is considered to be "less than" another string if 
it is lower in alphabetic order. For example, "CAT" is less 
than "DOG." Blanks are considered to be at the very beginning of 
the alphabet, so that " PPLE" is less than "APPLE." Finally, if 
two strings have the same leftmost characters, but one contains 
more characters then the other, the shorter string is less than 
the longer string. For example, "ABCD" is less than "“ABCDEF." 


STRING COMPARISONS 8.3 


STRINGS 78 


Strings may be compared with the word S< as follows: 


* CAT® * DOG* S< x K 

* DOG" * DOG" &X< . 

" CAT" " CATNAP” S< . 1 OK 
sites " S< . 1 OK 
NULL$ ° * S< . 1 OK 

NULL$ NULLS SX< . 


Null strings are less than character strings. Given S= and X< , 
you can easily define all other possible string comparisons. 
For example: 


: S>= ( GREATER OR EQUAL TO ) 
S< 0= ; 


8.3.2 Finding Substrings within Strings 


The word IN$ lets you find the first occurrence of one 
substring within another. IN$ returns the position of the 
match. If no match is possible, IN$ returns a zero: 


CAT DOG SEAL" BETA S! 


CAT" BETA INS . 
DOG" BETA INS$ OK 
" ANT" BETA INS OK 


NULL$ BETA INS . 0 OK 
NULL$ NULL$ INS . it OK 


8.4 STRING CONCATENATION 


A source string may be added to the end of a target string 
provided there is enough room at the end of the target string. 
Remember, only string variables can be used as target’ strings. 
The word S+ performs this concatenation. The definition of S+ 
given in appendix B makes use of RIGHT$ to define the target 
substring at the end of the target variable. As a result, S+ 
will always append at least one character to the target string. 
If the source string does not fit the end of the target string, 
as much of the source string as possible will be appended. If 
there is no room at all at the end of the target string, the 
last character of the target string will be changed to the first 
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character of the source string: 


ALPHA MLEN . 
" SEE IT " ALPHA S! OK 
ALPHA LEN . 7_OK 
" GO!" ALPHA S+ OK 
CR ALPHA TYPE 
SEE IT GOIOK 
NOW" ALPHA S+ OK 
CR ALPHA TYPE ~~ 
SEE IT GONOK 


" SEE IT " ALPHA S! OK 
" SWIM!" ALPHA S+ OK 
CR ALPHA TYPE 

SEE IT SWIOK 


8.5 CHARACTER & STRING CONVERSIONS 


Single characters are internally represented by a _ standard 
numbering system, usually the ASCII standard. To convert the 
first character in a string to its ASCII equivalent, use the 
word ASC as follows: 


" A" ASC . 65 OK 
m © ABC 
" ABC" ASC . 65 OK 


To reconvert an ASCII value into a source string of length one, 
use CHR$ as follows: 


65 CHRS$ TYPE 
CR 65 CHRS$ TYPE 32 CHRS TYPE 
A OK 


CHR$ creates its string in a temporary holding area. This 
string should be used as soon as possible. 


STR$ converts a double number to a temporary string. (See 
previous chapter for entering double numbers.) This temporary 
string is created in an extremely volatile location and should 
be immediately TYPEd or stored into a string variable: 


-123. STR$ ALPHA S! OK 
ALPHA TYPE — 

35 0 STR$ ALPHA S! 
ALPHA TYPE SPACE 35 OK 


Similarly, a string may be converted into a double number with 
the command VAL . Conversion follows the normal rules of 
entering numbers in the current base and stops with the first 
non-numeric character: 


*" -123" VAL D. - 

" 35M " VAL D. K 

" 40000" ALPHA S! OK 

ALPHA VAL D. 40000 OK 
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8.6 ARRAYS OF STRINGS 


You can create an array of related strings with the command 
STRING-ARRAY. For example, to create the string-array named 
PLANETS with 9 strings, each with a maximum of 7 characters, 
type: 


7 9 STRING-ARRAY PLANETS QK 


The elements in a _ string-array are numbered from zero. The 
Strings in PLANETS are numbered from zero to eight. Each 
element is a complete string, including a maximum length, and 
may be used as a target string. To specify the third string in 
PLANETS, you would type 2 PLANETS. Here are some examples: 


" EARTH" 2 PLANETS S! QK 

" MARS" 3 PLANETS S! OK 

2 PLANETS TYPE SPACE 

3 PLANETS TYPE SPACE MARS OK 





Warning: The results of a STR$ operation are stored ina 
temporary location. Because of this, 


-123. STRS$ 5 PLANETS S! 
may not work. Instead, use an intermediate string variable: 


-123. STRS$ ALPHA S! QK 
ALPHA 5 PLANETS S! QK 
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TABLE 8.1 STRINGS 
WORD STACK ACTION 


SPACE ( -=> ) Prints a blank space on the 
current output device. 

TYPE (st-adr n-len -->) Types the character sequence at 
starting address st-adr and 
current length n-len on the 
current output device. 


TABLE 8.2 STRING ENHANCEMENTS 


(The following commands are defined in appendix B. 
They are used as an example of a string package in FORTH.) 


WORD STACK ACTION 


STRING <name> Creates a string variable 
(n-max-length -->) with name <name> and 
maximum length n-max-length. 
(--> st-adr n-len) When executed, the starting address 


also shown as and current length of the string 
(--> str) will be left on the stack. 
LEN (str --> n-len) Finds current string length. 


ML EN (str --> n-max-len) Finds maximum string length. 
S! (str targ-str -->) Stores string into target string. 


*" ccc" (--> str) Creates literal string ccc, 
leaving its starting address and 
length on the stack. This string 
is temporary and may only be used 
as a source string. The string ccc 
must have at least one character. 


NULL$ (--> str) Creates a string with current 
length 0. 
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TABLE 8.2 STRINGS ENHANCEMENTS (continued) 


WORD STACK 
MID$ (strl n-pos n-len 
--> substring) 


RIGHTS (strl n-len 
--> substring) 


LEFTS (strl n-len 


--> substring) 


SUB! (strl substr2 -->) 


S= (strl str2 --> t/f) 


S< (strl str2 --> t/f) 


INS (strl str2 


--> npos) 
S+ (strl str2 -->) 
ASC (str --> n-ASCITI) 


CHR$ (n-ASCII --> str) 
VAL (str --> d-num) 
STRS (d-num --> str) 
STRING-ARRAY <name> 


(n-max n-dim -->) 


(n-index --> str) 


ACTION 


Forms a substring from strl. 
The substring begins at n-pos 
and has a length of n-len. 


Forms a substring from strl. 
The substring includes the n-len 
rightmost characters of strl. 


Forms a substring from strl. 
The substring starts at position l 
and has length n-len. 


Stores string strl into substring 
substr2. Does not disturb the 
current length of the string 
containing substr2. 


Returns "true" if strl equals str2. 
Otherwise returns "false." 


Returns "true" if strl is lower in 
alphabetic order than str2. 
Otherwise returns "false." 


Returns the position n-pos of the 
first occurrence of strl in str2. 
Returns 0 if no match is possible. 


Concatenates string strl to the 
the end of string variable str2. 
The current length of str2 is 
updated accordingly. 


Converts the first character of 
string str to its ASCII value. 


Converts an ASCII code to a 
temporary string str of length one. 


Converts the string str to a 
double number d-nun. 


Converts double number d-num 
to a temporary string str. 


Creates string-array named <name>. 
This array will contain n-dim 
strings of maximum length n-max. 
Upon execution, the starting address 
and current length of the n-index 
string in <name> will be left 

on the stack. 
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Often you will need to communicate with "the user" through 
the words (programs) you write in FORTH. The user is the person 
who will be sitting at the terminal at some later date, trying 
to use the program you have written. In fact, the user is 
likely to be yourself, long after you have forgotten how to use 
the program. For this reason, programs often include prompts 
and print explanatory messages. You must also be able to 
control the way printed output looks so that you can easily read 
its 


Programs may also need instructions from the user. "How 
many pages should I print?" or "Which item are you looking for?" 
are typical questions a program might need to ask. This means 
the program must allow you to enter numbers and strings directly 
from the keyboard. This chapter shows you some of the ways 
FORTH handles such user input and output. Before reading any 
farther, you should be sure that the user interface words are 
included in your FORTH dictionary. See chapter 1.0 (Getting 
Started) and appendix A.2 for details. 


2-1 SINGLE-CHARACTER INPUT AND OUTPUT 


The FORTH command KEY accepts a character from the standard 
input device (usually the keyboard). When KEY is executed, 
FORTH will patiently wait for you to type a character on your 
keyboard. As soon as you do, FORTH will translate this key into 
its ASCII value and push it on the stack. For example, try: 


KEY 


and RETURN. The cursor is probably waiting to the right of the 
comment for you. Notice that you do not see the usual OK. Now 
carefully type the letter A and RETURN. You should now see 
something like: 


KEY OK 


The letter A is not printed, but its ASCII value is now on the 
stack: 


- 2.0K 


You can now write a program that shows you the ASCII value for 


SINGLE-CHARACTER INPUT AND OUTPUT 9.1 


USER INTERFACE 84 


any key on your keyboard: 


: SEEKEY 
." KEY?" KEY . ; 
SEEKEY KEY?§6 OK ( "B" ) 
SEEKEY KEY?49 OK ( "1" ) 


Here are some other useful ASCII values: 


7 is "bell," which "beeps" some terminals. 
8 is "backspace." 
13 is "carriage return." 


Since KEY does not print, you could use it for entering 
secret passwords. You can also use KEY to select among 
different action alternatives: 


: READY? ( ARE YOU READY FOR THIS? ) 
CR ." READY (CR)? " 
KEY 13 ( RETURN KEY ) = ; OK 


: SAMPLE-WORD 
READY? 
IF ." ACTION TAKEN " 
ELSE ." STOPPED! " 
THEN ; OK 
SAMPLE-WORD ( HIT RETURN WHEN PROMPTED ) 
READY (CR)? ACTION TAKEN OK 
SAMPLE-WORD ( TYPE "N" WHEN PROMPTED ) 
READY (CR)? STOPPED! OK 
The word READY? leaves a "true" result on the stack if you hit a 
return key. If you hit any other key, it leaves a "false" 
result. This result is used by SAMPLE-WORD to see if you are 
indeed ready to take action. 


The word EMIT is opposite in action to the word KEY. EMIT 
removes an ASCII value from the stack and prints it: 


65 EMIT AOK 
EMITting a character of your choice can be very useful: 


: BELL 7 EMIT ; 
BELL ( BEEP! ) BELL ( BEEP! ) OK 


BELL emits a "bell character" which causes most terminals to 
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"beep." Backspacing can often be effectively combined with 
prompting: 


: BACKSPACE 8 EMIT ; 


: SUGGEST-5 
CR ." HOW MANY? 5" 
BACKS PACE 
KEY DUP EMIT ( ACCEPT KEY AND ECHO IT ) 
DUP 13 = ( RETURN KEY ) 
IF 5 
ELSE 48 ( ASCII "0" ) - 
THEN ; 


In SUGGEST-5, the BACKSPACE causes the input cursor to be 
repositioned over the suggested value 5. KEY accepts the next 
key, which replaces the 5 on the output device. DUP EMIT lets 
you see the number that you just typed. (While this is quite 
effective on a CRT terminal, it looks a little messy on a 
printer.) If the user simply hits the return key, the value 5 
will be left on the stack. If the user instead types a 
"numbered" key (from 0 to 9), the ASCII value of the key will be 
converted to the actual number and left on the stack. This is 
done by 48 -, which subtracts the ASCII value of 0O from the 
key. For example, typing a 4 puts the ASCII value 52 on the 
stack; 52 48 - then yields 4. The action of BELL and BACKSPACE 
may vary from terminal to terminal. Try them out on your 
terminal and see what they do! 


2.2 INPUT STRINGS AND NUMBERS 


The commands GET, GET$, INPUT, and INPUTS used in this 
section are defined in appendix B. These input commands are 
meant to be an example of the kinds of input words which can be 
written in FORTH. They make use of the string enhancements 
described in chapter 8, Strings. Be sure these words have been 
added to your FORTH language (see chapter 1.0, Getting 
Started). 


Sometimes questions can't be answered with single 
characters. What if you want to give a person's name or enter a 
number larger than nine? You would want to type a string of 
characters or numbers, perhaps backspacing to make corrections. 
When you were finished, you would hit the return key. FORTH 
would then accept the entire string or number and continue 
execution. 


The command INPUTS accepts a string of characters from the 
user, storing them in a temporary area. The starting address 
and number of characters are pushed on the stack. The string 
may then be manipulated with any of the string commands in 
chapter 8. Remember, a temporary string can only be used as a 
source string and should be used as soon as_ possible. The 
string created by INPUT$ can be up to 80 characters long. Any 
backspaces used to make corrections in the string are not 
included in the string. What you see (on a CRT display) is what 
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you get! Here is an example: 


80 STRING COMMAND OK 

CR ." >" INPUTS COMMAND S! ( TYPE "GO" ) 
>GO OK 

CR .” LET'S " COMMAND TYPE SPACE 

LET'S GO OK 


The string "GO" which you typed in response to the prompt ">" is 
now safely stored in the string variable COMMAND. 


The command INPUT accepts a double number from the user and 
puts it on the stack. You may wish to refer to Chapter 7 for 
details on using double numbers. The number is accepted when 
you hit the return key. You may freely use the backspace key 
while typing to correct numbers without affecting the final 
value. Numeric conversion is done in the current base. 
Conversion proceeds from left to right, stopping at the first 
non-convertible character. Here are some examples: 

CR INPUT D. ( TYPE -123 ) 

-123 =123_0K 

CR INPUT ( TYPE 47 ) 

47 OK 

CR ." THERE IS A“ D. .* ON THE STACK " 
THERE IS A 47 ON THE STACK OK 


CR INPUT D. ( TYPE 32,000 ) 
32,000 32 OK 


In the third example, conversion stopped at the (invalid) 
comma. 


If you need to restrict the number of characters typed by 
the user, you can use the commands GETS and GET. GETS is the 
same as INPUTS, except that you must specify the maximum number 
of characters (the "“width") to be accepted. In other words, 3 
GET$ will create a temporary string with no more than three 
characters. After the user has typed the third character, FORTH 
immediately accepts the string without waiting for a return 
key. For example: 


CR ." ANIMAL? " 5 GETS SPACE ( TRY "HIPPOPOTAMUS" ) 
rise BERGE HIPPO OK 
The hippopotamus was accepted after only five characters. 
In the same way, GET resembles INPUT, except that you must 


specify the width of the number. A minus sign is included in 
the count. In other words, 2 GET will accept any number from -9 
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to 99. For example: 


: WINDOW-IT ( ACCEPT A NUMBER WITHIN A WINDOW ) 
Ra" » < 
BACKSPACE BACKSPACE BACKSPACE 
2 GET." <* Dd 5 


WINDOW-IT ( TRY TO TYPE 123 ) 


>12< 12 OK 


Since GET was given a width of 2, FORTH accepted the number 
before you could type the "3." 


2-3 FORMATTING TEXT 


Most of your text formatting requirements can be met by 
TYPE-ing strings (see chapter 8). You can also use the words 
CR, SPACE, and even BACKSPACE (see above) to separate and align 
strings. In addition, FORTH provides a handful of other words 
to make formatting easier. SPACES prints multiple spaces. For 
example: 


CR ." FAR" 10 SPACES ." AWAY " 
FAR AWAY OK 


The argument that SPACES uses can be any computation that leaves 
a number on the stack. 


The word -TRAILING ("dash-trailing") can be used to shorten 
the apparent length of a string to exclude any trailing blanks. 
Only the copy of the current length on the stack is changed. 
Some examples should make this clear: 


" WASTED SPACE " CR -TRAILING TYPE 
WASTED SPACE OK 


" MORE SPACE " COMMAND S! OK 
COMMAND LEN . 

CR COMMAND -TRAILING TYPE 

MORE SPACE OK 

CR COMMAND TYPE 


MORE OK 
COMMAND LEN . 13 OK 


The word FILL fills any area of memory from a given 
Starting address with a given number of any given character. 
For example, 3000 100 0 FILL would store a zero at every memory 
location from 3000 to 3099 (100 locations). Because a string 
argument actually consists of its starting address and current 
length, FILL can be used to fill a string with repetitions of 
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any character up to its current length: 


CR COMMAND TYPE 

MORE SPACE OK 

COMMAND 37 ( ASCII "%" ) FILL OK 
CR COMMAND SPACE TYPE 
TESSEEESSESES OK 


You can clear any string by filling it with blanks to its 
maximum length with the following sequence: 


32 CONSTANT BL ( ASCII " " BLANK ) OK 
COMMAND DROP COMMAND MLEN BL FILL OK 


The constant BL makes remembering the ASCII value for a blank 
somewhat easier. 


2-4 FORMATTING NUMBERS 


In chapter 2, you learned the command .R to print a 
right-justified number in a field of characters. In chapter 7, 
you learned how to use D.R to format double numbers in the’ same 
way. But suppose you have to print the number in a 
left-justified field, or with an imbedded decimal point? 
Fortunately, FORTH lets you completely control the format of the 
numbers you print. 


First, you should DUP the number and put it in a safe place 
(in a variable or deeper down on the stack). Next convert the 
number to a double number if necessary (see chapter 7). Now use 
DABS to leave the unsigned double number on the stack. Finally, 
execute the word <# ("less-sharp"). This word has no effect on 
the stack; it sets up a temporary area to store the characters 
you form as you convert the number for printing. 


The word # ("sharp") converts one digit of the number in 
the current base and saves it in the temporary holding area. 
This digit is removed from the number. For example, suppose the 
(decimal) number 123 is on the stack. After the first #, the 
character "3" would be added to the holding area and the number 
12 would be left on the stack. The word #S ("sharp-s") converts 
all of the remaining digits of a number to characters in the 
holding area, leaving a double-number zero on the stack. 


The word SIGN adds the character - ("minus") to the holding 
area if the number on top of the stack is negative. The number 
is removed. Remember the original copy of the number kept in a 
safe place? Now is the time to push it on the stack, right over 
the double-number zero. SIGN checks (and destroys) this number, 
leaving the double-number zero. 


Finally, the word #> ("sharp-greater") ends the conversion 
process. The double-number zero is dropped, and the _ starting 
address and current length of the holding area are left on the 
stack. These two arguments look like a source string and can be 
used by any of the string functions (as discussed in chapter 
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8). 


At any time in the conversion process you can insert 
special characters into the holding area with the word HOLD. 
For example, to insert a decimal point use 46 HOLD, where 46 is 
the ASCII code for a_ period. Suppose you want to print a 
decimal point in the hundred's position: 


: »HUNDRED ( PRINT BY HUNDREDS ) 
( REQUIRES UNSIGNED DOUBLE-NUMBER ARGUMENT ) 
<# # # 46 HOLD #S #> {86 35 ASCTT 2% } 
TYPE ; OK 


45993. .HUNDRED 459,93 OK 


Perhaps you have some money in the bank: 


: eMONEY ( PRINT MONEY ) 
OVER OVER DABS 
<# # #46 HOLD ( PENNIES ) 
#S 36 HOLD ( 36 IS ASCII "$" ) 
DROP DROP DUP SIGN ( MINUS MONEY? ) 
#> TYPE ; OK 


12345. MONEY 

-9999. MONEY - 
With a little more work, you could expand this to put a comma in 
the thousand's position, and so forth. 
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TABLE 2.1 USER INTERFACE 


WORD STACK 


KEY 


EMIT 


SPACES 


( --> n-ASCII ) 


( n-ASCII --> ) 


( n --> ) 


-TRAILING (strl --> str2) 


FILL 


<# 


#S 


SIGN 


#> 


TABLE 9.1 


(adr n-len n2 
may J 


(udl --> ud2) 


(ud --> 0 0 ) 


(n --> ) 


(dn --> string) 


USER INTERFACE 


ACTION 


Leaves the ASCII value of the next 
key typed on the parameter stack. 


Prints the character whose ASCII 
value is on the stack on the 
current output device. 


Prints n spaces. 


Adjusts the current length of a 
string argument on the stack to 
exclude any trailing blanks in 

the string. 


Fills an area of memory starting at 
adr with n-len copies of byte n2. 


Prepares a temporary holding area 
to use for converting a number to 
a string of characters. 


Converts a digit to a character. 
The udl is then divided by BASE 
to produce ud2. 


Converts all remaining digits of 
ud until only a double-number 
zero is left on the stack. 


Adds the ASCII char "-" to the 
holding area if n is negative. 


Ends conversion. Drops dn, leaving 
the starting address and length of 
the character string in the holding 
area. 
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TABLE 2.1 USER INTERFACE (Continued) 


(The following words have been added to FORTH. You will find 
their definitions in appendix B.) 


WORD STACK ACTION 


GET (n-width --> dn) Inputs a double number from 
the keyboard. The input field 
is limited to width n-width. 


INPUT ( --> dn) Inputs a double number from the 
keyboard. 
GETS (n-width --> str) Inputs a character string from the 


keyboard. The string is kept in a 
temporary holding area. The input 
field width (string length) is 
limited to n-width. 


INPUTS ( --> str) Inputs a character string from the 
keyboard. The string is kept ina 
temporary holding area. The string 
is limited to 80 characters. 
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In this final chapter, we will touch upon some of the more 
powerful but complex aspects of the FORTH language. To treat 
each of these in detail would require an additional volume as 
large as this one. If you are interested in continuing your 
study of FORTH, we urge you to read carefully the special FORTH 
issue of BYTE magazine (August 1980). You should also study the 
word definitions in appendix B and the glossary of FORTH words 
in appendix C. We also suggest you subscribe to FORTH 
DIMENSIONS (see chapter 1). 


10.1 EXCEPTIONAL CONDITIONS 


You can terminate the execution of a word (in FORTH-79) at 
any time with the command EXIT (see chapter 5). On a somewhat 
larger scale, you can terminate the execution of all words and 
return to the execution (keyboard entry) mode with the command 
QUIT. QUIT clears the return stack, changes to "execution mode" 
(see below), and returns control to your terminal. 


The command ABORT, like QUIT, clears the return stack, 
changes to execution mode, and returns control to the terminal. 
ABORT also clears the parameter stack. QUIT is normally used to 
terminate execution of a program when a task is completed (or 
determined to be unnecessary). ABORT is normally used to 
terminate execution of a program which has encountered a serious 
error. (MicroMotion FORTH also includes the command ONERR. See 
appendix J for details.) 


10.2 USER VOCABULARIES 


When you type a line from the keyboard or LOAD a= screen, 
FORTH searches the dictionary for each word it reads and 
executes or compiles it. This search begins with the most 
recent word. If you have several definitions of the same word, 
FORTH will use the one you defined most recently. The command 
VOCABULARY lets you create a separate dictionary for a 
particular application which will be searched first. (By the 
way, the vocabulary (dictionary) you have been using up to now 
is named FORTH.) To create a dictionary called MYNAMES, type: 


VOCABULARY MYNAMES IMMEDIATE OK 


(The IMMEDIATE command will be discussed below.) 


USER VOCABULARIES 10.2 


ADVANCED TOPICS 93 


To enter a definition into a vocabulary, use the command 
DEFINITIONS: 


MYNAMES DEFINITIONS QK 
: TASK2 ; OK 

st = 3 

FORTH DEFINITIONS OK 


The word TASK2 and the new definition of + ("plus") are now in 
vocabulary MYNAMES. Now list the top of the dictionary: 


VLIST ( OR SOME SIMILAR COMMAND ) 
MYNAMES 

SETFLASH 

oe c@tCece 


Notice that TASK2 and + are apparently not in the dictionary. 
If you tried to execute TASK2 at this point, you would get an 
error message. 


To activate a vocabulary, simply type the name of the 
vocabulary: 


MYNAMES OK 
VLIStT ~~ 
+ 

TASK2 
MYNAMES 
SETFLASH 


oe c@tCoee 
Now study the following sequence: 


MYNAMES QK 


324+. io 
FORTH OK 


32a* « SOF 


When the MYNAMES vocabulary was active, it was searched first 
for the + command (whose definition was simply - ("minus"). 
Notice that the print command . ("dot") was successfully 
executed, even though it is in the FORTH vocabulary. This is 
because the FORTH dictionary is always searched for words that 
can't be found in the other vocabulary. 


10.3 CREATE AND DOES> 


One of FORTH's most powerful features is the ability to 
create new classes of objects with the commands CREATE and DOES> 
(called <BUILDS and DOES> in FIG-FORTH). These objects can be 
viewed as intelligent data structures, or perhaps as words with 
data storage. The command CREATE specifies what actions wiil be 
taken when an object of a given class is created. The command 
DOES> specifies what actions will be taken when an object of a 
given class is executed. You can find a detailed discussion of 
CREATE and DOES> in "Forth extensibility: Or how to write a 
compiler in twenty-five words or less" by Kim Harris in BYTE 
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(August 1980, pp 164-184). 


Consider the definition of CARRAY, which was used in 
chapter 3 to create arrays of bytes: 


: CARRAY ( CREATE OBJECTS OF CLASS CARRAY ) 
CREATE ALLOT 
DOES> + ; OK 


10 CARRAY ITEMS QK 


0 ITEMS . 

3 ITEMS . tite 
The word CREATE (<BUILDS) in the definition of CARRAY creates 
objects of class CARRAY. Whenever the word CARRAY appears, a 
new word is created in the dictionary whose name is the word 
which follows CARRAY. In this case, the word is named ITEMS. 
No parameter field storage space is allocated by CREATE. The 
words which follow CREATE are then executed. In this case, the 
Single word ALLOT is executed. So 10 CARRAY ITEMS puts a ten on 
the stack and creates the word ITEMS. The word ALLOT then 
executes and creates storage space in the parameter field for 10 
bytes. 


The command DOES> ensures that when any word created by the 
preceding CREATE is executed, the address of the parameter field 
of that word will be pushed on the stack and control will 
transfer to the FORTH words following the DOES>. In the above 
example, 3 ITEMS will first push a three and then the parameter 
field address of ITEMS on the stack. Control then transfers to 
the + operator, which adds the two arguments. The result is the 
address of the third byte in the byte array ITEMS. 


10.4 EXECUTION AND COMPILATION 


When you are typing commands from the keyboard (or LOADing 
them from screens), FORTH executes each word as soon as you hit 
the return key. This is called the "execution" mode. If you 
enter a definition by typing a : ("colon"), FORTH will compile 
the words you type until you finish the definition with a ; 
("semicolon"). This is called "compilation" mode. The words 
within the definition are not executed until you type the name 
of the definition (in execution mode). In fact, the : changes 
the mode from execution to compilation and the ; changes it back 
again. 


There is a third class of words in FORTH called "compiler 
words." These words are executed instead of compiled when used 
within a definition (that is, in compilation mode). FORTH uses 
these words to control the compilation process itself. Words 
like IF, BEGIN, DO, and so forth are examples of compiler 
words. You can turn any word into a compiler word by following 
its definition with the command IMMEDIATE. 
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You don't need to know how to use compiler words to program 
in FORTH. You can write effective and complete programs in 
FORTH without ever having to use a compiler word (except the 
flow of control words you learned in chapter 5). However, if 
you wish to try defining a compiler word of your own, we 
recommend you look up the following words in appendix C to see 
how they work: 


COMPILE 
[COMPILE] 
[ 


] 

STATE 
LITERAL 
EXECUTE 


WORD 
EXPECT 
QUERY 


10.5 USING MACHINE CODE 


Most FORTHs have a built-in assembler for generating 
machine-language code. The FORTH-79 standard does not’ specify 
exactly how this assembler should behave. You will find the 
details of the MicroMotion assembler in appendix H. If you are 
using another FORTH, you should study the description of the 
assembler provided with the FORTH. 


Most FORTHs also have some command to transfer control to 


machine-language subroutines. (See the command CALL in appendix 
G.) 
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TABLE 10. 


WORD STACK 


QUIT ( --> ) 


ABORT ( --> ) 


VOCABULARY <name> 


DEFINITIONS ( --> ) 


CREATE <name> 


( --> address) 


DOES> ( ==> ) 


IMMEDIATE ( --> ) 


TABLE 10.1 ADVANCED TOPICS 
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1 ADVANCED TOPICS 
ACTION 


Clears the return stack, changes to 
execution mode, and returns to the 
terminal. 


Clears the data and return stacks. 
Changes to execution mode 
and returns to the terminal. 


Effectively creates a separate 
dictionary of name <name>. 
When <name> is executed, FORTH 
will first search for words in 
<name> and then in the FORTH 
dictionary. 


Allows you to enter definitions 
into the dictionary most recently 
activated. 


Creates a dictionary entry <name> 
but does not allocate any storage 
space in the parameter field. 

When <name> is later executed, the 
address of the first byte of this 
parameter field will be left on the 
stack. 


Specifies the execution-time action 
of a word created in the form 
: <name> CREATE ... DOES> ... ;7 


Marks the last-compiled word so that 
it will be executed rather than 
compiled if found within a word 
definition. 
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* * 
* * 
* * 
* APPLE II STARTUP * 
* * 
* * 


REEEEKREKEEKEKKKKKKKKKKKEE 


KEEKKEEKKEKEKKEEKEEKEKEKEEKKEEKEKKEKKKKKKKKKK 


* 

" NOTE: Please do not remove 
= the write-protect tab 

ia on the grandfather disk. 
& 
* 


+e + + F 


REEKEKKEKEKEEKKEKKEKKEKKEKEEKEKKEKKKKEKKE 


Insert your FORTH grandfather disk in disk drive 1 and boot 
up in the usual manner. The FORTH grandfather disk is Apple DOS 
3.2 (13-sector) compatible. If you are using Apple DOS 3.3 
(16-sector) you will first need to BRUN BOOT13 from your 
System-Master disk or boot up on your BASICS disk. 


REEKKEKKEKEEKEKREKEEEKERKEKEKEKKKKKKKKKE 


* * 
* NOTE: The grandfather disk ” 
* should always be booted from ~ 
* drive l. ? 
x * 
* * 


REKKKKEKEKEEKKKEKEKEEREKKKKKKKKKKKKK 


After boot up, you should see the following hello message 
displayed on your screen: 


FORTH-79 DOUBLE NUMBER YER 2.0 
MICROMOTION 12077 WILSHIRE #506 
L-A.-, CA. 20025 213-821-4340 
COPYRIGHT 1981 


If you do not see this display, you should try rebooting. If 
you are using Apple DOS 3.3, don't forget to BRUN BOOT13 or boot 
BASICS first. If you still do not see this display, then your 
grandfather disk is defective and should be _ returned to 
MicroMotion for replacement. 


Underneath this display, you will briefly see: 
MEMORY TEST: PLEASE STANDBY 


All available memory (0000 to BFFF hex) is tested. If the 
memory test fails, you will see a message such as: 


MEMORY ERROR IN BIT 1 AT ADDR 7D0 


A.0 


APPLE II STARTUP 98 


The bit and the address give you the location of the error. You 
must first replace the defective memory chip before running 
FORTH. 


Next you will be asked: 
HOW MANY DRIVES (1-4)? 


Type the single digit specifying the number of disk drives you 
have in your system. The number you type will appear to the 
right of the question. 


EKEKEKEKKKEEEEKEEKKEEKEKEEKEEREEKKKKKKEK 
* 


* NOTE: If you enter the wrong * 
* number in the disk drive = 
* configuration sequence, please * 
* reboot the grandfather disk * 
: and start the sequence again. ° 
* * 


KREKKKKEEKEKKKKEKEKKEKEKEKKEEKEEKKKEKKKEE 


Now you should see: 


DRIVE 1 IN SLOT (1-2)? 


Enter the (single-digit) slot number containing the disk 
controller card. Next you will be asked: 


DR (1-2)? 
Enter the drive number (1 or 2) of your first drive. 


Suppose you have two drives in slot 6. Your configuration 
sequence would be: 


HOW MANY DRIVES (1-4)? 2 
DRIVE #1 IN SLOT (1-2)? & DR (1-2)? 1 
DRIVE #2 IN SLOT (1-2)? 6 DB (1-2)? 2 


In FORTH, each mass storage device is divided into blocks 
(data) or screens (text). In a FORTH-79 standard system, each 
block/screen is 1024 bytes long. Blocks/screens are described 
more fully in chapter 6 (The Editor & Mass Storage). In 
MicroMotion's FORTH, each drive provides 113 blocks (13-sector) 
or 140 blocks (16-sector) of mass storage. Each drive is spaced 
1000 (decimal) blocks from the preceding drive. In other words, 
the first block of drive 1 is block 0, the first block of drive 
2 is block 1000 (decimal), and the third block of drive 4 is 
block 4002. 


The final question in the configuration sequence is: 
CHANGE TO 16-SECTOR (X/N)? 
Type "Y" if you have 16-sector (Apple DOS 3.3) disk drive(s); 


otherwise, type "N" or "return." Drive 1 (containing the 
grandfather disk) will briefly spin as grandfather prepares 
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itself for the disk production sequence. 


A-1 CREATING FORTH DISKETTES 


You will now be asked: 
CREATE (BLANK) FORTH DISK (X/N)? 


Answer "yes" (type "Y") if you wish create FORTH backup disks. 
The grandfather disk is copy-protected and should only be used 
for disk configuration or to produce backup disks. You will 
need at least one backup disk to use in learning FORTH. You 
will see the warning: 


ek 


IMPORTANT 
*** REMOVE OLD DISK FROM DR#l 
*** INSERT NEW DISK IN DR#l 
HIT ANY KEY WHEN READY: 


Remove the grandfather disk and put it in a safe place. Insert 
a blank disk in drive 1 and hit any key. The drive will spin 
and the message *FORMATTING* will appear on the screen. It will 
take a few minutes to format the disk and initialize all screens 
to blanks. 


Next you will be asked: 


CREATE DICTIONARY (X/N)? 


If you answer "no" ("N"), you will be left with a disk full of 
blank screens, suitable for text or data storage only. If you 
answer "yes" ("Y¥"), the FORTH dictionary will be copied to the 
lowest screens on the disk (about 25 screens). You will then be 
able to boot FORTH directly from this disk. You will also be 
able to SAVE future dictionaries on this disk. Screens not 
occupied by the dictionary are available for data or text 
storage. If you wish to combine dictionary and data or text on 
a disk, remember that if you SAVE a new and larger dictionary, 
it may overwrite some of your data or text. It is always safe 
to use screens 50 (decimal) and higher for data or text. 


RREEKKKKEKEKEEKEKEEEKKEKKKKKKKEKKKKKKKKKK 


NOTE: You can only SAVE 
dictionaries on a disk which 
already has a dictionary. 


++ + + + & 
+e + + % 


REKEEKKEKEEKEEKKEKEKREEKKKKKRKKKKKKKKKKKK 


You have now returned to the question: 


CREATE (BLANK) FORTH DISK (X/N)? 
You may create as many backup disks as you like by repeating 


this sequence. When you are finished, answer "no" ("N") to this 
question. You will be returned to 13-sector format. You can 
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change to 16-sector format by booting up on any 16-sector backup 
disk which contains a copy of the dictionary. Whenever you need 
more backup disks, you need only reboot the grandfather disk 
(from drive 1) and repeat the configuration and production 
sequence. 


FORTH is now ready for you to use. Here is one final note 
on the Apple keyboard: 


RKEKKKEEKKKEEKKEEEKEKEEEEKRKEEKEKKKKKKKEK 


* 
* NOTE: The left and right * 
* square brackets [ ] * 
* are created by typing ctrl1-N * 
* and shift-M respectivly. * 
* * 
* * 


KREKKEKEKEKKKEEKEEEKEKKEEKKKEKKEKKKKKKKKE 


You may now return to chapter 1 (Getting Started) and continue 
reading. When you have learned how to EDIT and LOAD words into 
your dictionary, you should return to this appendix to learn 
about the many useful utilities provided on the grandfather disk 
(described below). 


A.-2 FORTH EXTENSIONS AND UTILITIES 


The grandfather disk contains the source screens for many 
FORTH extensions and utilities. Boot grandfather and answer 
"no" ("N") to all production sequence questions. You will be 
left in 13-sector FORTH. EDIT screen 40 (decimal) and you will 
see: 


SCR# 40 
( SYSTEM SCREENS BEGIN ) 
DECIMAL OPTIMIZER 
( 37 39 .... ( RESERVED: 16-SECT RWTS ) 
41 43 THRU ( DISK ) 
44 LOAD ( RANDOM NUMBER GENERATOR ) 
45 46 THRU ( CASE ) 
( 47 LOAD ( DOUBLE-NUMBER EXTENSION ) 
( 48 49 THRU ( LOWER CASE ) 
( 30 61 THRU ( STRING EXTENSION ) 
( 62 64 .... ( ASCII >CHARS DOC HUNT ) 
65 LOAD ( HELLO GO TURNKEY ONERR ) 
( 66 LOAD ( SELECTIVE DESTRUCT ) 
68 69 THRU ( APPLE UTILITIES ) 
( 70 72 THRU ( LORES GRAPHICS ) 
( 73 94 .... ( UTILITIES ) 
( 25 29 THRU ( 79-STANDARD DEFINITIONS ) 


Screen numbers that appear outside of comments contain 
definitions which have already been compiled into your 
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dictionary. The utility screens 73 through 94 may be further 
subdivided: 


73 CATALOG. 

74 / LOOP 

75-76 Some debugging tools. 

77-78 INFO and a more powerful VLIST. 
79-81 COPY-BLOCKS and COPY-DISK. 

82-83 REFORMAT Ver 1.2 screens to Ver 2.0. 


84 16-Sector track/sector alternate skew. 
85 RECONFIGURE slots and drives. 

86 Ver 1.2 ASSEMBLER Conditionals. 

87-90 Some extra arithmetic functions. 

91 PAUSE and MS 

92 Ver 1.2 definitions not in Ver 2.0. 


93-94 13-SECTOR and 16-SECTOR conversion words. 


The words supplied on these screens are more fully described in 
appendix C (The Glossary). 


For example, if you wish to move the string enhancement 
screens 50 through 61 from the grandfather disk to a 16-sector 
backup, you must first add the 13-sector and 16-sector 
conversion utilities to your dictionary: 


93 94 THRU 
«+ FORGET TASK AFTER CONVERSION OK 


The words 13-SECTOR and 16-SECTOR have been added to your 
dictionary. You may now transfer the string enhancement 
screens: 


6 BUFFERS QK ( You may use more buffers. ) 
50 50 6 LOAD-BUFFERS OK ( Insert 16-sector backup. ) 
16-SECTOR 

SAVE-BUFFERS QK ( Insert grandfather. ) 
13-SECTOR 

56 56 6 LOAD-BUFFERS OK ( Insert 16-sector backup. ) 
16-SECTOR 


SAVE-BUFFERS QK 
FORGET TASK OK 


Note: the word 16-SECTOR uses an alternate 16-sector disk 
system, which is copied into the dictionary from grandfather 
screens 37 through 39. To save dictionary space, FORGET TASK 
when the conversion is complete. 


A.3 CONVERTING FORTH-79 VERSION 1.2 TO VERSION 2.0 


MicroMotion FORTH-79 version 2.0 offers several 
improvements over version 1.2. The compiler has been redesigned 
to aid in producing portable source code (see appendix M). The 
assembler now supports local labels and conditional branches 
(see appendix H). The screen editor has been enhanced to allow 
you to move multiple lines within and across’ screens (see 
appendix F). Source screens are now structured as 16 lines of 
64 characters. The editor has been modified to flip right and 
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left to let you see all 64 characters. You have probably 
already noticed the addition of the word THRU, which allows you 
to LOAD a range of screens. You may still use --> within a 
screen to LOAD a range of screens, but be careful not to mix --> 
with THRU, or you are likely to LOAD a screen several times. 


If you have source screens written in version 1.2 and would 
like to convert them to 2.0, you must first reformat them with 
the word REFORMAT. You will find this word on the grandfather 
disk. If you need to reformat source screens on a 16-sector 
disk, first load the 16-sector conversion screens (see above). 
Now type in the starting screen number and the number of screens 
you wish to reformat, followed by the word REFORMAT. 
Reformatting screens generates extra screens, so be sure that 
you have extra room at the end of the _ screens. You should 
probably move the screens to a blank FORTH disk with 
LOAD-BUFFERS and SAVE-BUFFERS (or the utility COPY-BLOCKS on the 
grandfather) before you begin reformatting. REFORMAT will tell 
you how many screens are required and will let you cancel the 
operation if there isn't enough room: 


10 20 REFORMAT ( Reformat screens 10 through 29 ) 
22 BLOCKS WILL BE GENERATED. OK (X/N)? 


Typing "Y" will reformat screens 10 through 29, which will then 
occupy screens 10 through 38. After conversion, you can FORGET 
TASK to recover dictionary space. 


Some words in version 1.2 are missing from version 2.0. 
You will find the definitions for these words on the grandfather 
utility screen 92. You will also find the ASSEMBLER 
conditionals IF, ELSE, THEN, BEGIN, WHILE, REPEAT, and UNTIL, on 
the grandfather utility screen 86. You should probably replace 
any such conditionals in your CODE words with conditional 
branches to local labels (see appendix H). 
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* 
* * 
* * 
* SUPPLEMENTARY DEFINITIONS * 
* * 
* * 


REEKKEKKEKEEKKEEKEEKEEEKKEEEEKEKKKKKKES 


The following word definitions are not included in the 
FORTH-79 standard. The words themselves are fully described in 
the text, however. Their definitions are organized by the 
chapter in which they first appear. All definitions are 
cumulative, that is, later definitions may depend on earlier 
ones. Numbers are given in hexadecimal unless otherwise noted. 


All definitions are given using the FORTH-79 Standard word 
set. Alternate sequences using the FIG-FORTH word set are given 
whenever necessary. If you have purchased MicroMotion FORTH-79, 
all definitions have already been added to your dictionary. 
Otherwise, someone who is familiar with the FORTH system you 
will be using should study these definitions and add them to the 
dictionary for you. 


Chapter 2. Stacks and Numbers 


Add these definitions to FIG-FORTH: 


: l- l- 
: 2- 2- 


=e =e 


Two new useful arithmetic operators are: 


: 2* 2% 3 
¢ar 2s 


Remember that 2/ will propagate the sign bit. 
Add PICK and ROLL to FIG-FORTH: 


: PICK 
2* SP@ + @; 
: ROLL 
DUP 1+ PICK 0 ROT 2* 
DO SP@ I + DUP 2- @ SWAP ! -2 
+LOOP DROP ; 


All of the above definitions should be recoded in machine code 
for greater speed. 


You can give FORTH-79 names to some FIG-FORTH words: 


R@ R; 
?DUP -DUP ; 
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The print command .R uses other definitions which must also 
be added to FORTH-79. These additional words are described in 
chapter 7, More About Numbers. 


: S=->D 
DUP O0< IF -1 ELSE 0 THEN ; 
: DABS 
DUP 0< IF DNEGATE THEN ; 
D.R 
>R SWAP OVER DABS 
<# #S SIGN #> R> 
OVER - SPACES TYPE ; 
¢ oR 
>R S->D R> D.R ; 


Chapter 3. Constants & Variables 
The definition of C, should be: 


: C, 
HERE 1 ALLOT C! ; 


The FORTH-79 array and table words are: 


: CARRAY 
CREATE ALLOT 
DOES> + ; 

: ARRAY 


CREATE 2* ALLOT 
DOES> SWAP 2* + ; 
: CTABLE 
CREATE 
DOES> + C@ ; 
: TABLE 
CREATE 
DOES> SWAP 2* + @ ; 


In FIG-FORTH, substitute <BUILDS for CREATE. 


Chapter 4. Words and the Dictionary. 
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The examples in this chapter make use of the random number 
generator RANDOM : 


DECIMAL 
: HEX 16 BASE ! ; ( First define HEX ) 
HEX ( set HEX mode ) 
VARIABLE SEED ( FORTH-79 ) 
or 
0 VARIABLE SEED ( Most other FORTHs ) 
followed by 
: SETSEED 
OABC SEED ! ; 
: $RN ( 16 bit random number ) 
SEED @ 4000 AND 0= 
SEED @ 2* DUP >R 4000 AND O= XOR 
R> OR DUP SEED ! ; 
RANDOM ( N --> 0<=RANDOMXN ) 
$RN 7FFF AND SWAP MOD ; 


f 


The command SETSEED could be replaced by a FORTH word which sets 
SEED to be some random number taken from the host computer. 


Chapter 5. Flow of Control 
Add these words to FIG-FORTH: 


: 0> 

0> >; 
: J 

R> R> R> I 4 ROLL 4 ROLL 4 ROLL >R OR OR ; 
These words should be recoded in machine code for greater 
speed. 


The word EXIT is defined thus: 


: EXIT 
COMPILE ;S ; IMMEDIATE 


The definitions given for the CASE and GODO commands’ use 
several FIG-FORTH compiler primitives. These words insure that 
the compilation is syntactically correct. The following 
definitions will work correctly in FIG-FORTH and MicroMotion 
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FORTH-79 but may not work on other FORTH-79 systems: 


: CASE 


Chapter 7. 


?COMP CSP @ !CSP 4 ; IMMEDIATE 
OF 

4 ?PAIRS COMPILE OVER COMPILE = 

COMPILE OBRANCH HERE 0 , 

COMPILE DROP 5 ; IMMEDIATE 
ENDOF 

5 ?PAIRS COMPILE BRANCH 

HERE 0 , SWAP 2 

[COMPILE THEN 4 ; IMMEDIATE 
ENDCASE 

4 ?PAIRS COMPILE DROP 

BEGIN SP@ CSP @ = 0= 

WHILE 2 [COMPILE THEN 

REPEAT CSP ! ; IMMEDIATE 
(GODO) 

2* 0 MAX R@ @ 4 — MIN R> DUP DUP 

@ + >R + 2+ @ EXECUTE ; 
GODO 

COMPILE (GODO) 

HERE 0 , 2 ; IMMEDIATE 


More About Numbers 


FIG-FORTH is missing the definitions of four words (D< D. 


U< and U.): 


FORTH- 


D. 
0 D.R ; 
U. 

0D. ; 
U< 

OVER OVER XOR 0< 

IF SWAP DROP 0< 

ELSE < 

THEN ; 
D< 

ROT OVER OVER = 

IF DROP DROP U< 

ELSE > SWAP DROP SWAP DROP 
THEN ; 


79 is missing the definitions of three words (M* M/ 


B.0 
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and M/MOD). These mixed-precision words are defined in 
FIG-FORTH: 


st 
0< 
IF NEGATE 
THEN ; 
: D+- 
0< 
IF DNEGATE 
THEN ; 


: M* 
OVER OVER XOR >R 

| el SWAP ABS U* R> D+-— ; 
: M 

OVER >R >R DABS R@ ABS U/MOD 

R> R@ XOR +- SWAP R> +- SWAP ; 
M/MOD 

>R 0 R@ U/MOD R> SWAP >R U/MOD R> ; 


Chapter 8. Strings 


The following string package is completely described in 
chapter 8: 


: STRING ( N-MAX --> ) 
CREATE 1 MAX 255 MIN 
DUP C, 0 C, ALLOT 
DOES> 1+ COUNT ; 


Note: FIG-FORTH uses <BUILDS for CREATE. 


: (*) 


R@ COUNT DUP 1+ R> + OR ; 


Note: (") depends on the internal FORTH structure. The address 
of (") is compiled into a word definition by the word " (see 
below) and is followed by the string. The first byte of the 
string gives its length. The word (") should push the string 
arguments (starting address and length) of the following string 
on the stack. Flow of control should then be altered to skip 
the string and continue with the following word. 


: TEXT 
PAD 1+ 40 BLANKS WORD COUNT 
DUP PAD C! ?DUP 
IF PAD 1+ SWAP CMOVE 
ELSE DROP 
THEN ; 
2 " 
22 STATE @ 
IF COMPILE (") WORD C@ 1+ ALLOT 
ELSE TEXT PAD COUNT 
THEN ; IMMEDIATE 
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Note: FIG-FORTH uses WORD HERE for WORD in both of 
definitions. 


: S! 
DROP DUP 2 - C@ 
ROT MIN DUP 3 PICK 1 — C! CMOVE ; 
: LEN 
SWAP DROP ; 
: MLEN 
DROP 2 —- C@ ; 
: MIDS 
>R OVER MIN 1 MAX 1 - 
SWAP OVER - R> MIN >R + RD ; 
: RIGHTS 
OVER 1+ SWAP —- OFF MIDS ; 
: LEFTS 
1 SWAP MIDS ; 
: SUB! 
ROT MIN 0 MAX CMOVE ; 
: S= 
ROT OVER = 
IF ?DUP 
IF 1 SWAP 0 
DO DROP OVER C@ OVER C@ = 
IF 1+ SWAP 1+ SWAP 1 
ELSE 0 LEAVE 
THEN 
LOOP 
ELSE 1 
THEN 
ELSE DROP 0 


THEN SWAP DROP SWAP DROP ; 


: S< 
ROT OVER MIN SWAP OVER > >R ?DUP 
IF -1 SWAP 0 
DO DROP OVER C@ OVER C@ = 
IF 1+ SWAP 1+ SWAP -1l 
ELSE C@ SWAP C@ > LEAVE 
THEN 
LOOP DUP 0< 
IF DROP DROP DROP R> 
ELSE R> DROP 
THEN 
ELSE DROP DROP R> 
THEN ; 


: S+ 
>R OVER R@ + OVER 2 - C@ MIN OVER OVER 
SWAP 1 - C! R> 1+ OFF MIDS SUB! ; 


: CHRS 

PAD ! PAD 1 ; 
: ASC 

DROP C@ ; 
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the above 
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: INS 
DUP 4 PICK —- DUP 0> 
IF SWAP OVER - 
IF 0 SWAP 2+ 1 
DO DROP 3 PICK C@ OVER C@ = 
IF 3 PICK 3 PICK 3 PICK OVER S= 


IF I LEAVE 
ELSE 1+ 0 
THEN 
ELSE 1+ 0 
THEN 
LOOP 
ELSE DROP 0 
THEN >R DROP DROP DROP R> 
ELSE DROP S= 
THEN ; 


: VAL 
DROP 0. ROT 1 - CONVERT DROP ; 


Note: FIG-FORTH uses (NUMBER) for CONVERT in this context. 


: STRS 
SWAP OVER DABS 
<# #S ROT SIGN #> ; 


Note: FIG-FORTH uses SIGN for ROT SIGN. 


: STRING-ARRAY 
CREATE 0 
DO DUP C, 0 C, DUP ALLOT 
LOOP 
DOES> DUP C@ 2+ ROT * + 1+ COUNT ; 


Note: FIG-FORTH uses <BUILDS for CREATE. 


Chapter 9. User Interface 


The following definitions are provided for user interface. 
They are considered to be extensions of the string words 
described in chapter 8. 


: GETS 

PAD SWAP ACCEPT PAD COUNT ; 
INPUTS 

40 GETS ; 


GET 

GETS VAL ; 
INPUT 

40 GET ; 


Note: Fully commented listings of the string and user functions 
can be found in the source screens supplied with MicroMotion 
FORTH-79. 
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C.1 GLOSSARY NOTATION 


C.1.1 Order 

The glossary definitions are listed in ASCII alphabetical 
order. 
C.1.2 Stack Notation 


The first line of each entry describes the execution of the 
definition: 


0 stack parameters before execution 
--- showing point of execution 
stack parameters after execution 
ie, before --- after 


In this notation, the top of the stack is to the right. 
Words may also be shown in context, when appropriate. 


C.1.3 Attributes 


Capitalized symbols indicate attributes of the defined 
words: 


C The word may only be used within a colon-definition. 


I Indicates vhat the word is IMMEDIATE and will execute 
during compilation, unless spgcial action is taken. 


U A user variable. 


FORTH Standard definitions have a serial number 
assigned, in the range 100 thru 999. 


C.1.4 Capitalization 


Word names as used within the dictionary aru conventionally 
written in upper-case characters. Within this glossary, lower 
case will be used when reference is made to the run-time machine 
code, which is not directly accessible. For example, VARIABLE is 
the uwer word to create a variable. Each use of that variable 
makes use of a code sequence '‘'variable' which executes’ the 
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function of the particular variable. 


C.1.5 Pronunciation 

The pronunciation of FORTH names is given in double quotes 
(") 
C.1.6 Stack Parameters 


Unless otherwise stated, al| references to numbers apply to 
16-bit signed integers. 


The implied range of values is shown as {from..to}. The 
content of an address is shown by double curly brackets, 


particularly for the contents of variables. i.@e, BASE 
{{2..70}} 
addr {0..65535} 


A value representing the address of a byte within the 
FORTH standard memory space. This addressed byte may 
represent the first byte of a larger data field in 
memory. 


byte {0.255} 


A value representing an 8-bit byte. When the byte 
appears in a larger field, the higher bits are zero. 


char {0.1273 
A value representing a 7-bit ASCII character code, 
When the byte appears in a larger field, the higher 
bits are zero. 

d {-2,147,<83,648..2,147,483 ,647} 


32-bit signed double number. The most significant 16 
bits, with sign, are most accessible on the stack. 


flag 
A numerical value with two logical states; zero equals 
false, non-zero equals true. 

n {-32,768..32,767} 
16-bit signed integer number. 

ud {0..4,294,967,295} 


32-bit unsigned integer number. 
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un {0..65,535} 
16-bit unsigned integer number. 


Any other symbol refers to an arbitrary signed 16-bit 
integer in the range {-32,768..32,767}, unless 
otherwise noted. 


C.1.7 Input Text 


<name> 


An arbitrary FORTH word accepted from the input 
stream. This notation refers to text from the input 
stream, not to values on the data stack. If the input 
stream is exhausted before encountering <name>, an 
error condition exists. 
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#> 


#DRS 


#S 


&) 


C.2 FORTH WORD SET 


n addr --- 112 
Store n at address. "store" 
udl --- ud2 158 


Generate from an unsigned double number udl, the next ASCII 
character which is placed in an output string. Result ud2 
is the quotient after division by BASE and is maintained 
for further processing. Used between <# and #>. "sharp" 


d --- addr n 190 


End pictured numeric output conversion. Drop d, leaving 
the text address, and character count, suitable for TYPE. 
"sharp-greater" 


--- n-drives 


A constant set by the grandfather disk to be equal to the 
number of disk drives in the system. #DRS may be reset by 
RECONFIGURE. 


ud --- 0 0 209 


Convert all digits of an unsigned 32-bit number ud, adding 
each to the pictured numeric output text, until remainder 
is zero. A single zero is added to the output string if 
the number was initially zero. Use only between <# and 
#>. "“sharp-s" 


A portable-bracket delimiter. See appendix M. 
--- addr I,171 
Used in the form: 
‘ <name> 


If executing, leave the parameter field address of the next 
word accepted from the input stream. If compiling, compile 
this address as a literal; later execution will place this 
value on the stack. An error condition exists if not found 
after a search of the CONTEXT and FORTH vocabularies. 
Within a colon-definition ' <name> is identical to [ ' 
<name> ] LITERAL. “tick" 


"FORGET -—- I 


A compile-only word used in the form: 
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"FORGET <name> 


When the word containing 'FORGET is later executed, <name> 
will be forgotten. See FORGET. 


( I,122 
Used in the form: 


( cccc) 


{tream 
As a word, the left 
blank. It may be 
compiling. An error 
is exhausted before 


Accept and ignore comment characters from the input 
until the next right parenthesis. 
parenthesis must be followed by one 
freely used while executing or 
condition exists if the input stream 


the right parenthesis. "paren" The right parenthesis is 
Pronounced "close-paren" 

(& --- 
Indicates the beginning of a portable-bracket, OPTIMIZER 
mode. See appendix M. 

(( ee 
Indicates the beginning of a portable-bracket, 79-STANDARD 
mode. See appendix M. 

(+LOOP) n --- Cc 
The run-time procedure compiled by +LOOP. 

Ce") 0 0 c 
The run-time procedure compiled by ." "dot-quote". 

(/LOOP) n --- Cc 
The run-time procedure compiled by +LOOP. 

(:) ve 
The run-time procedure compiled by : "colon". 

(; CODE) Cc 
The run-time procedure compiled by ;CODE. 

( ?KEY) --- flag 
The machine-code subroutine which is called by ?KEY. It is 
terminated by a return-from-subroutine instruction. See 


appendix A. 
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(ABORT) --- addr 


A variable containing the CFA of the word to be used by 
ABORT. The value is set by ONERR. 


(ADDR) -—- 
System use only. 

(BELL) --- 
The default word called by BELL. The CFA of (BELL) is 
stored in the element 5 of the vector array SEVEC. See 
SEVEC and BELL. 

(BOOT) --- addr 


A variable containing the CFA of the word to be called 
after booting the disk. The value is set by TURNKEY. 


(C/) <= 
System use only. 
(CH) n--- 
The default word called by CH. The CFA of (CH) is stored 
oe element 2 of the vector array SEVEC. See SEVEC and 
(CON) =—= A 
The run-time procedure compiled by CONSTANT. 
(COPY) --- 
System use only. 
(CV) n--- 
The default word called by CV. The CFA of (CV) is stored 
an Se element 3 of the vector array SEVEC. See SEVEC and 
(DO) c 


The run-time procedure compiled by DO which moves the loop 
control parameters to the return stack. See DO. 


(DOES>) 
The run-time procedure compiled by DOES. 
(EMIT) char --- 
The machine-code subroutine which is called by EMIT. It is 


terminated by a return-from-subroutine instruction. See 
EMIT, IOVEC, and appendix M. 
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(FIND) addrl addr2 --- addr3 byte flag (match) 
addrl addr2 --- flag (no match) 


Search the dictionary starting at the name field address 
addr2, matching to the text at addrl. Returns parameter 
field addresss addr3, length byte of name field and true 
flag for a good match. If no match is found, only a_ false 
flag is left. 

(FORGET) --- 
System use only. 

(GODO) e 
The run-time procedure compiled by GODO. 


( HOME ) ——— 


The default word called by HOME. The CFA of (HOME) is 
stored in the element 4 of the vector array SEVEC. See 
SEVEC and HOME. 

(KEY) --- ch 


The machine-code subroutine which is called by KEY. It is 
terminated by a return-from-subroutine instruction. See 
KEY, IOVEC, and appendix M. 

(INFO) =e 
System use only. 

(L/S) ooem 
System use only. 

(LINE) n --- addr n2 
Convert the line number n to a string argument (addr ‘n2), 
indicating the position and length of that line in the most 
recently accessed disk buffer. 

(LIT) --- n 
The run-time procedure compiled by LITERAL or by any number 
appearing within the definition of a word. The actual 
value of the number is compiled to follow LIT in the 
dictionary. When executed, the value n is left on the 
stack. 

(LOOP) Cc 


The run-time procedure compiled by LOOP. 
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(R/W) —— 
System use only. 

(TDONE) --- 
The default word called when exiting the editor. The CFA 
of (TDONE) is stored in the element 1 of the vector array 
SEVEC. See SEVEC. 

(TINIT) --- 
The default word called by EDIT to initialize the editor. 
The CFA of (TINIT) is stored in the element 0 of the vector 
array SEVEC. See SEVEC. 

(VAR) --- addr 
The run-time procedure compiled by VARIABLE, 

)) nee 
A portable-bracket delimiter. See appendix M. 

* nl n2 --- n3 138 
Leave the arithmetic product of nl times n2. "times" 

*/ nl n2 n3 --- n4 200 
Multiply nl by n2, divide the result by n3 and leave the 
quotient n4. n4 is rounded toward zero. The product of nl 
times n2 is maintained as an intermediate 32-bit value for 


a greater precision than the otherwise equivalent 
sequence: nl n2 * n3 / "tiles-divide" 


/ne 4 
* /MOD 0 nl n2 n3 --- n4 n5 192 


Multiply nl by n2, divide the result by n3 and leave the 
remainder n4 and quotient n5. A 32-bit intermediate 
product is used, as for */. The remainder has the same 
sign as nl. "times-divide-mod" 

+ nl n2 --- n3 121 
Leave the arithmetic sum of nl plus n2. "plus" 

+1 n addr --- 157 


Add n to the 16-bit value at the address, by the convention 
given for +. “plus-store" 


+BUF addrl --- addr2 flag 
Advance the block buffer address addrl to the address of 


the next buffer addr2. Flag is false when addr2 is the 
buffer presently pointed to by variable PREV. 
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+LOOP 


a peare I,C,141 


Add the signed increment n to the loop index using the 
convention for + and compare the total to the limit. 
Return execution to the corresponding DO until the new 
index is equal to or greater than the limit (n>0) or until 
the new index is less than the limit (n<0). Upon exiting 
from the loop, discard the loop control parameters, 
continuing execution ahead. Index and limit are _ signed 
integers in the range {-32,768..32,767}. "plus-loop" 


(Comment : It is historical precedent that the limit for 
n<0 is irregular. Further consideration of the 
characteristic is likely.) 

n--- 143 


Allot two bytes in the dictionary, storing n_ there. 
"comma" 


nl n2 --- n3 134 


Subtract n2 from nl and leave the difference n3. "minus" 


==> I 
Continue interpretation with the next sequential screen. 
("next-screen"). 

-TRAILING addr nl --- addr n2 148 


FORTH WORD SET 


Adjust the character count nl of a text string beginning at 
addr to exclude trailing blanks, ie, the characters at 
addr+n2 to addr+nl-1l are blanks. An error condition exists 
if nl is negative. "dash-trailing" 


ee 193 


Display n converted according to BASE in a free-field 
format with one trailing blank. Display only a negative 
sign preceeding a negative number. "dot" 


I,133 
Interpreted or used in a colon-definition in the form: 
+” cece" 


Accept the following text from the input stream, terminated 
by ASCII " (double quote). If executing, transmit this 
text to the selected output device. If compiling, compile 
so that later execution will transmit the text to the 
selected output device. At least 127 characters are 
allowed in the text. If the input stream is exhausted 
before the terminating double quote, an error condition 
exists. "“dot-quote" 


‘?) 
e 
tS 
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oR nl n2 --- 


Print the number nl right aligned in a field whose width is 
n2. No following blank is printed. 


-S --- 
A non-destructive stack print. Prints the current contents 
of both the parameter and the return stack. 

f nl n2 --- n3 178 
Divide nl by n2 and leave the quotient n3. n3 is rounded 
toward zero. "divide" 

/ LOOP un --- 
A DO-LOOP terminating word. The loop index is incremented 
by unsigned number un. Until the resultant index exceeds 
the limit, execution returns to just after the 
corresponding DO. Otherwise the index and limit are 
discarded. Magnitude logic is used. "up-loop" 

/MOD nl n2 --- n3 n4 198 
Divide nl by n2 and leave the remainder n3 and quotient 
n4. n3 has the same sign as nl. "“divide-mod" 

GizZgs --—- n 
These small numbers are used so often that it is attractive 
to define them by name in the dictionary as constants. 

0< n--- flag 144 
True if n is less than zero (negative). "“zero-less" 

0= n --- flag 180 
True if nis zero. "zero-equals" 

0> --- flag 118 
True if n is greater than zero. "“zero-greater" 

OBRANCH flag --- Cc 
The run-time procedure to branch conditionally. If flag is 
false, the following in-line parameter is added to the 
interpretive pointer to branch ahead or back. Compiled by 
IF, UNTIL, and WHILE. 

1+ n --- ntl 107 


Increment n by one, according to the operation for +. 
“one-plus" 
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1- n--- n-l 105 
Decrement n by one, according to the operation —. 
"one-minus” 
13-SECTOR -—— 
Prepares the operating system to read a 13-sector disk. 
16-SECTOR = 


Prepares the operating system to read a 16-sector disk. 


16-SECTOR-V1.0 --- 


Prepares the operating system to read a MicroMotion ver. 
1.0 16-sector disk or an APPLE DOS 3.3 disk. 


16-SECTOR-V2.0 --- 


Prepares the operating system to read a MicroMotion ver. 
1.1 or ver. 1.2 or ver. 2.0 disk. 


2* n --- n*2 
Multiply n by two, using a shift-left for greater speed. 

2+ n --- n+2 135 
Increment n by two, according to the operation for +. 
"two-plus"” 

2- n --- n-2 129 
Decrement n by two, according to the operation for -. 
"two-minus" 

2/ n --- n/2 
Divide n by two, using a shift-right for greater speed. 
The sign-bit is propagated. 

79-STANDARD 119 


Execute assuring that a FORTH-79 Standard system is 
available, otherwise an error condition exists. Sets WIDTH 
to 31. 


116 
A defining word used in the form: 


: <name> eee 3} 


Select the CONTEXT vocabulary to be identical to CURRENT. 
Create a dictionary entry for <name> in CURRENT, and set 
compile mode. Words thus defined are called ‘colon 
definitions'. The compilation addresses of subsequent 
words from the input stream which are not immediate words 


FORTH WORD SET C.2 


GLOSSARY 121 


=e 


are stored into the dictionary to be executed when <name> 
is later executed. IMMEDIATE words are executed as 
encountered. 


If a word is not found after a search of the CONTEXT and 
FORTH vocabularies, conversion and compilation of a literal 
number is attempted, with regard to the current BASE; that 
failing, an error condition exists. "colon" 


I,C,196 


Terminate a colon definition and stop compilation. rf 
compiling from mass storage and the input stream is 
exhausted before encountering ; an error condition exists. 
"semi-colon" 


See appendix C.4 


7S I 
Stop interpretation of a screen. ;S is also the run-time 
word compiled at the end of a colon-definition which 
returns execution to the calling procedure. 

< nl n2 --- flag 139 
True if nl is less than n2. 
-32768 32767 < must return true. -32768 O must be 
distinguished. "less-than" 

<# 169 
Initalize pictured numeric output. The words: 

<# # #S HOLD SIGN #> 

can be used to specify the conversion of a double number 
into an ASCII character string stored in right-to-left 
order. "“less-sharp" 

<CMOVE addrl addr2 n --- 
Copy n bytes beginning at addrl to addr2. The move 
proceeds within the bytes from high memory toward low 
memory. "“reverse-c-move" 

= nl n2 --- flag 173 
True if nl is equal to n2. “equals” 

> nl n2 --- flag 102 


True if nl if greater than n2. "“greater-than" 
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»< nl --- n2 
Swap the high and low bytes within nl. "byte-swap" 
>CHARS addrl nl --- addr2 n2 


Convert a string of bytes to a string of characters by 
masking off the high-order bit. 


>IN --- addr U,201 
Leave the address of a variable which contains the present 
character offset within the input stream. {{0..1023}} 
"to-in" 
See: WORD ( ." FIND 

>R n --- C,200 
Transfer n to the return stack. Every >R_ must be 
balanced by a R> in the same control structure nesting 
level of a colon definition. "to-r" 

? addr --- 194 


Display the number at address, using the format ".". 
"question-mark" 


?) char --- 
System use only. 
?ALLOT --—- 
System use only. 
?DUP ne-=-- n (n ) 184 


Duplicate n if it is non-zero. "“query-dup" 


?ERROR flag n --- 
Issue an error message number n, if the boolean flag is 
true. 

? FIND --- CFA 


Leave the compilation address of the next word name, which 
is accepted from the input stream. An "UNKNOWN?" error 
message is printed if the word cannot be found. 


?KEY --- flag 
Perform a test of the terminal keyboard for actuation of 


any key. A true flag indicates actuation. This definition 
is installation dependent. 
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?STACK <= 

System use only. 
@ addr --- n 199 

Leave on the stack the number contained at addr. "fetch" 
ABORT 101 


Clear the data and return stacks, setting execution mode. 
Return control to the terminal. 


ABS nl --- n2 108 
Leave the absolute values of a number. "absolute" 
ALLOT n--- 154 


Add n bytes to the parameter field of the most recently 
defined word. 


AND nl n2 --- n3 183 
Leave the bitwise logical "and" of nl and n2. 
ARRAY n--- 
A defining word executed in the form: 
n ARRAY <name> 


to create a dictionary entry for <name> and allot n 
two-byte elements in the parameter field. 


When executed later: 
n <name> 


will place the storage address of the nth element of the 
array on the stack. 


ASCII --- char I 

Used in the form: 
ASCII <char> 

Determines the ASCII value of <char>, the next character in 
the input stream. The ASCII run-time action is to leave 
this value on the stack. The compile-time action is to 
compile this value as a LITERAL. 

ASSEMBLER I,166 


See appendix C.4 
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B/BUF =“-=- 1 


A constant that leaves the number of bytes per block 
buffer, the byte count read from mass storage by BLOCK. 


B/DR --- n 
A constant that leaves the number of blocks per disk 
drive. 

BASE --- addr U,115 


Leave the address of a variable containing the current 
input-output numeric conversion base. {{2..70}} 


BEGIN I,C,147 
Used in a colon definition: 


BEGIN ... flag UNTIL or 
BEGIN ..- flag WHILE ... REPEAT 


BEGIN marks the start of a word sequence for repetitive 
execution. A BEGIN-UNTIL loop will be repeated until flag 
is true. A BEGIN-WHILE-REPEAT loop will be repeated until 
flag is false. The words after UNTIL or REPEAT will be 
executed when either loop is finished. Flag is always 
dropped after being tested. 


BELL 
Emits a control-G on the current output device, causing the 
system "bell" to ring. 

BL --- char 176 
A constant that leaves the ASCII value for "blank." 

BLK --- addr U,132 
Leave the address of a variable containing the number of 
the mass storage block being interpreted as the input 
system. If the content is zero, the input stream is taken 
from the terminal. "b-1l-k" {{unsigned-number}} 

BLOCK n --- addr 191 


Leave the address of the first byte in block n. If the 
block is not already in memory, it is transferred from the 
mass storage into whichever memory buffer has been least 
recently accessed. If the block occupying that buffer has 
been UPDATEd (ie, modified), it is rewritten onto mass 
Storage before block n is read into the buffer. n is an 
unsigned number. If correct mass storage reading or 
writing is not possible, an error condition exists. Only 
data within the latest block referenced by BLOCK are valid 
by byte address, owing to sharing the block buffers. 
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BRANCH Cc 


The run-time procedure to branch unconditionally. An 
in-line offset is added to the interpretive pointer IP to 
branch ahead or back. BRANCH is compiled by ELSE, AGAIN, 
REPEAT, 


BS --- char 
Leave the ASCII "delete character"(7F hex) on the stack. 
BUFFER n --- addr 130 


Obtain the next block buffer, assigning it to block n. The 
block is not read from mass_ storage. If the previous 
contents of the buffer have been marked as UPDATEd, it is 
written to mass_ storage. If correct writing to mass 
storage is not possible, an error condition exists. The 
address left is the first byte within the buffer for data 
storage. n is an unsigned number. 


BUFFERS n--- 
Execute SAVE-BUFFERS. Allocate n buffers in memory, 
limiting n to not less than 2 and not greater than MAXBUF. 
Execute EMPTY-BUFFERS. 

Cc! n addr --- 219 
Store the least significant 8 bits of n at addr. "“c-store" 

c* unl un2 --- un3 
A fast 8-bit by 8-bit multiply, which leaves n3, an 
unsigned 16-bit product of the least significant 8 bits of 
unl times the least significant 8 bits of un2. 

C, byte --- 
Store 8 bits of byte into the next available dictionary 
byte, advancing the dictionary pointer by one. This is 
only available on byte-addressing computers, and should be 
used with caution on byte-addressing minicomputers. 
"c-comma" 

C/ 8-bit-nl 8-bit-n2 --- 8-bit-un3 
A fast 8-bit by 8-bit divide. The least significant 8 bits 
of unl is divided by the least significant 8 bits of un2 to 
leave the 8-bit unsigned quotient n3. 

C/L --- n 


,A constant leaving 64, the number of characters per line of 
source text. 
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C/SL --- n 


Leave the number of characters per line on the CRT output 
device. 


ce addr --- byte 156 


Leave on the stack the contents of the byte at addr (with 
higher bits zero, in a 16-bit field). "“c-fetch" 


CALL addr --- 
Transfer control to the machine-code subroutine whose 
address is on the stack. Machine registers will be loaded, 
then saved, from a reserved memory area. See appendix G. 
CARRAY n--- 
A defining word executed in the form: 


n ARRAY <name> 


to create a dictionary entry for <name> and allot n one 
byte elements in the parameter field. 


When executed later: 
n <name> 


will place the storage address of the n-th element of the 
array on the stack. 


CASE 
Used in a colon-definition in the form: 
nl CASE 
n2 OF ... ENDOF 
n3 OF ... ENDOF 
n x OF eee ENDOF 
otherwise-words 
ENDCASE 
A selector is an expression leading to a number, nl. If nl 
equals n2, n3 or =~*nx,_ both ns are removed and the words 
within the respective OF...ENDOF will be executed. 
Execution will continue following the ENDCASE. If nl does 
not equal n2, then n2 is removed and nl is tested for 
equality with n3. This continues through nx until a match 
occurs. If no match occurs, nl will be on the stack and 
the otherwise-words will be executed, after which nl is 
removed. Case has no run-time effects. 
CATALOG nl n2 --- 


List each line in screens nl through n2 whose first 
character is non-blank. 
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CFA addrl --- addr2 


Convert addrl, the parameter field address of a definition, 
to its code field address, addr2. 


CH i: === 

Position the cursor to column n. 
CLRSCR -—< 

Clear the Lo-Res graphics screen. 
CLRTOP -—- 


Clear the graphics portion of the mixed text and Lo-Res 
graphics screen. 


CMOVE addrl addr2 n --- 153 
Move n_ bytes from address addrl to addr2. The contents 
of addrl are moved first, proceeding toward high memory. 
If n is zero or negative nothing is moved. "c-move" 

CODE 111 


See appendix C.4 


COLD 
The cold start procedure to adjust the dictionary pointer 
to the minimum standard and restart via ABORT. May be 
called from the terminal to remove application programs and 
restart. 

COLOR n --- 
Sets the default Lo-Res graphics HLINE and VLINE color to 
n. Constants are provided with the Lo-Res’ graphics 
enhancements for the more common colors: BLACK, MAGENTA, 
D-BLUE, D-GREEN, BROWN, ORANGE, YELLOW, and WHITE. 

COMPILE C,146 


When a word containing COMPILE executes, the 16-bit value 
following the compilation address of COMPILE is copied 
(compiled) into the dictionary, ie, COMPILE DUP will copy 
the compilation address of DUP. 


COMPILE [ 0 , ] will copy zero. 
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CONSTANT nN --- 185 
A defining word used in the form: 
n CONSTANT <name> 


to create a dictionary entry for <name>, leaving n_ in its 
parameter field. When <name> is later executed, n will be 
left on the stack. 


CONTEXT --- addr U,151 


Leave the address of a variable specifying the vocabulary 
in which dictionary searches are to be made during 
interpretation of the input stream. 


CONVERT dl addrl --- d2 addr2 195 


Convert to the equivalent stack number the text beginning 
at addl+l with regard to _ BASE. The new value is 
accumulated into double number dl, being left as d2. Addr2 
is the address of the first non-convertible character. 


COPY-BLOCKS nl n2 n3 --- 
A basic utility program for copying and reordering blocks. 
Copy n3 blocks from block nl to n2. You will be asked 
"Pause after load?" If you answer "yes" (Y), you will be 
given a chance to change disks between loading and saving. 

COPY-DISK --- 
This utility will allow you to copy an all source text 
disk. Copyed dictionaries will not boot. It is 
self-prompting. 

COUNT addr --- addr+l n 159 
Leave the address addr+l and the character count of text 
beginning at addr. The first byte at addr must contain the 
character count n. Range of n is {0..255}. 


CR 160 


Cause a carriage-return and line feed to occur at the 
current output device. "c-r" 


Note: In the Apple version, the line feed is removed in 
(EMIT). 


CREATE 239 
A defining word used in the form: 
CREATE <name> 


to create a dictionary entry for <name> without allocating 
any parameter field memory. When <name> is subsequently 
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executed, the address of the first byte of <name>'s 
parameter field is left on the stack. 


CSP --- addr U 
A user variable temporarily storing the stack pointer 
position for compilation error checking. 

CTABLE n--- 
A defining word executed in the form: 

n CTABLE <name> 
to create a dictionary entry for <name>. No bytes are 
ALLOTed in the parameter field. Elements are created with 
C, ("c-comma"). 
When executed later: 
n <name> 

will place the value of the nth element of the table on the 
stack. CTABLE is the byte-equivalent of TABLE. 

CURRENT --- addr U,137 
Leave the address of a variable specifying the vocabulary 
into which new word definitions are to be entered. 

CV n--- 
Positions the cursor to row n. 

D+ dl d2 --- d3 241 
Leave the arithmetic sum of dl plus d2. "d-plus"” 

D.R dn--- 
Display d converted according to BASE, right-aligned in an 
n-character field. Display the sign only if negative. 
"d-dot-r" 

D< dl d2 --- flag 244 
True if dl is less than d2. "d-less” 

DABS dl --- d2 
Leave as a positive double number d2, the absolute value of 
a double number dl. {0..2,147,483,647} “d-abs” 

DECIMAL 197 


Set the input-output numeric conversion base to ten. 
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DEFINITIONS LSS 


Set CURRENT to the CONTEXT vocabulary so that subsequent 
definitions will be created in the vocabulary previously 
selected as CONTEXT. 


DEPTH mex 238 


Leave the number indicating the quantity of 16-bit values 
contained in the data stack before n was added. 


DESTRUCT 


Destroys all IMMEDIATE words. FORTH programs will execute 
normally, but new words cannot be added to the dictionary. 


DIGIT char nl --- n2 true-flag (valid) 
char nl --- false-flag (invalid) 


Using base nl, convert a character to its binary equivalent 
n2, accompanied by a_ true-flag. If the conversion is 
invalid, leave only a false-flag. 


DLITERAL d --- d (executing) I 
d --- (compiling) 


If compiling, compile a stack double number into a 
literal. Later execution of the definition containing the 
literal will push it to the stack. If executing, the 
number will remain on the stack. 


DNEGATE dl --- -dl 245 
Leave the two's complement of a double number. 

DO nl n2 --- I,C,142 
Used in a colon definition: 


DO ..- LOOP or 
DO ..- +LOOP 


Begin a loop which will terminate based on control 
parameters. The loop index begins at n2 and is terminated 
based on the limit nl. At LOOP or +LOOP, the index is 
modified by a positive or negative value. The range of a 
DO-LOOP is determined by the terminating word. DO-LOOPs 
may be nested. Capacity for three levels of nesting is 
specified as a minimum for standard systems. 


DOC nl n2 --- 
Display on the current output device screens from nl to n2. 


The screens are printed in “pages" of three screens per 
page, followed by an ASCII "form-feed" character. 
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DOES> I,C,168 


Define the run-time action of a word created by a 
high-level defining word. Used in the form: 


: <mame> ... CREATE ... DOES> ..e } 
and then <name> <namex> 


Mark the termination of the defining part of the defining 
word <name> and begin the definition of the run-time action 
for words that will later be defined by <name>. On 
execution of <namex>, the sequence of words between DOES> 
and ; will be executed, with the address of <namex>'s 
Parameter field on the stack. "does" 


DP --- addr U 
A user variable, the dictionary pointer, which contains the 
address of the next free memory above the dictionary. The 
value may be read by HERE and altered by ALLOT. "d-p"” 

DR# --~ 
System use only. 

DROP n --- 233 
Drop the top number from the stack. 

DUMP addr n --- 
Prints a hexadecimal and ASCII dump, 8 bytes per line. 
Starting at addr, n bytes are dumped. 

DUP n--- nn 205 
Leave a copy of the top stack number. 

EDIT nh === 
Select the EDITOR as the CONTEXT vocabulary and edit screen 
n. 

EDITOR teliZ 
The screen-oriented editing vocabulary, selected by EDIT 
and WHERE. 

ELSE I,C,167 


Used in a colon definition: 
IF eee ELSE eee THEN 
ELSE executes after the true part following IF. ELSE 


forces execution to skip till just after THEN. It has _ no 
effect on the stack. (See IF) 
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EMIT char --- 207 
Transmit character char to the current output device. 


Note: The Apple version of (EMIT) translates ASCII "delete" 
($7F) to ASCII "backspace" ($08). 


EMPTY-BUFFERS 145 
Mark all block buffers as empty, without necessarily 
affecting their actual contents. UPDATEd blocks are not 
written to mass storage. 

ENCLOSE addrl char --- addrl nl n2 n3 
Using the character as a delimiting character, scan text 
beginning at addrl. Return nl, the byte offset to the 
first non-delimiter character, n2, the offset to the first 
delimiter after the text, and n3, the offset to the first 
character not included. This procedure will not process 
past an ASCII "null," treating it as an _ unconditional 
delimiter. ENCLOSE is the text-scanning primitive used by 
WORD. 

ERR -—- 
System use only. 

ERR# -—— 
System use only. 

ENDCASE 
See CASE. 

ENDOF 
See CASE. 

EXECUTE addr --- 163 


Execute the dictionary entry whose compilation address is 
on the stack. 


EXIT €;117 
When compiled within a colon definition, terminate 
execution of that definition at that point. May not be 
used within a DO-LOOP. 

EXPECT addr n --- 189 
Transfer characters from the terminal beginning at addr, 
upward, until a "return" or the count of n_ has been 


received. Take no action for hn _ less then or equal to 
zero. One or two nulls are added at the end of text. 
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FENCE --- addr U 


A user variable containing an address below which 
forgetting is trapped. To forget below this point the user 
must alter the contents of FENCE. 


FILL addr n byte --- 234 
Fill memory beginning at addr with a sequence n copies of 
byte. If the quantity is less than or equal to zero, take 
no action. 

FIND --- addr 203 


Leave the compilation address of the next word name, which 
is accepted from the input stream. If that word cannot be 
found in the dictionary after a search of CONTEXT and 
FORTH, leave zero. 

FIRST --- addr 


A constant that leaves the address of the first (lowest) 
block buffer. 


FORGET 186 

Execute in the form: 
FORGET <name> 

Delete from the dictionary <name> (which is in the CURRENT 
vocabulary) and all words added to the dictionary after 
<name>, regardless of their vocabulary. Failure to find 
<name> in CURRENT or FORTH is an error condition. 

FORTH I,187 


The name of the primary vocabulary. Execution makes FORTH 
the CONTEXT vocabulary. 


New definitions become a part of FORTH until a differing 
CURRENT vocabulary is established. 


User vocabularies conclude by "chaining" to FORTH, so FORTH 
should be considered "contained" within each users' 
vocabulary. 

FROM --- addr 


System use only. 
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GO --- 
The default system coldstart word. GO prints the "hello" 
message, empties the disk buffers, and transfers control to 
WARM. 

GODO n--- I,c 
Used in a colon definition: 

n GODO word0O wordl ... wordx THEN 

The nth word between GODO and THEN will be executed. 
Execution will then continue after THEN. If n is less than 
Or equal to zero, word0O will be executed; if nis 1, wordl 
will be executed, and so on. If n is greater than or equal 
to x, wordx will be executed. 

HELLO === 
The default system "hello" message. 

HERE --- addr 188 
Return the address of the next available dictionary 
location. 

HEX 162 
Set the input-output numeric conversion base to sixteen 
(hexadecimal). 

HILO nl --- n2 n3 
Split nl into two bytes. The low-order byte is n2 and the 
high-order byte is n3. Both numbers are padded to the left 
with a zero-byte. 

HIMEM -<—- n 
A constant leaving the address just above the highest 
memory available for the FORTH dictionary to use. 

HIRES --- addr 
Leave the base address of Hi-Res graphics page 1 on the 
stack. This 8k region is not used by FORTH, and the 
address can be used as the start of an 8K-byte memory 
array. 

HLD --- addr 


A user variable that holds the address of the latest 
character of text during numeric output conversion. 
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HLINE 


HOLD 


HOME 


HUNT 


nl n3 n3 --- 
Draw a Lo-Res horizontal line from column nl to column n2 
in row n3. The line is drawn in the color last set by 
COLOR. 

char --- 175 


Insert character into a pictured numeric output string. 
May only be used between <# and #>. 


Position the cursor to the upper-left corner of the CRT and 
clear the CRT display to blanks. 


nl n3 --- 
Use in the form: 

nl n2 HUNT cccc 
Hunt searches screens nl to n2 for a match with string 
cccc. The string ends with a "return." The screen and line 


number of all matches is printed on the default system 
output device. 


I --- n C,136 
Copy the loop index onto the data stack. May be only used 
within a DO-LOOP. 
I/L --- n 
Leave the recommended input line length on the stack. 
IBLOCK 
System use only. 
ID. addr --- 
Print a definition's name from its name field address. 
IF flag --- I,C,210 


Used in a colon definition: 


flag IF ... ELSE ... THEN or 
flag IF ... THEN 


If flag is true, the words following IF are executed and 
the words following ELSE are skipped. The ELSE part is 
optional. 


If flag is false, words between IF and ELSE, or between IF 
and THEN (when no ELSE is used), are skipped. IF-ELSE-THEN 
conditionals may be nested. 
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IMMEDIATE 103 


Mark the most recently made dictionary entry as a word 
which will be executed when encountered during compilation 
rather than be compiled. 


IN# n--- 


Apple II only: Select card slot n as the current character 
input device. 


INDEX nl n2 --- 


Print the first line of each screen over the range from nl 
to n2. This is used to view the comment lines of several 
text screens. 


INTERPRET 


The outer text interpreter which sequentially executes or 
compiles text from the input stream (terminal or mass 
storage) depending on STATE. If the word name cannot be 
found after a search of CONTEXT and then FORTH, it is 
converted to a number according to the current base. That 
search also failing, an error message echoing the name with 
a "?" will be given. Text input will be taken according to 
the convention for WORD. If a decimal point is found as 
part of a number, a double-number value will be left. The 
decimal point has no other purpose’ than to force this 
action. See NUMBER, 


IN? -——— 
System use only. 
INFO ——— 
Use in the form: 
INFO <name> 
A one-line fancy VLIST is printed for the word <name>. 
IOVEC --- addr 
A system variable with enough space allocated to hold the 
four input/output vectors used by: KEY, EMIT, ?KEY, and 
R/W. The first three vectors point directly to 
machine-code, which must terminate with a 
return-from-subroutine instruction. The fourth vector 
points to the CFA of the FORTH word called by R/W. See 
appendix M. 
J ara | C,225 


Return the index of the next outer loop. May be used only 
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within a nested DO-LOOP in the form: 
DO eee DO eee J eee LOOP eee LOOP 
KEY --- char 100 


Leave the ASCII value of the next available character from 
the current input device. 


Note: The Apple version of (KEY) translates ASCII 
"backspace" ($08) to ASCII "delete" ($7F). 


L/S --- n 


Leave the recommended number of lines/CRT-output-screen on 
the stack. 


LCKEY = 


Sets the KEY vector to accept lower case keys from the 
Apple keyboard. See also UCKEY. 


LATEST --- addr 


Leave the name field address of the topmost word in the 
CURRENT vocabulary. 


LEAVE C,213 
Force termination of a DO-LOOP at the next LOOP or +LOOP by 
setting the loop limit equal to the current value of the 
index. The index itself remains unchanged, and execution 


proceeds normally until the loop terminating word is 
encountered. 


LFA addrl --- addr2 


Convert addrl, the parameter field address of a definition, 
to its link field address, addr2. 


LIMIT =-= Ti 


A constant leaving the address just above the highest 
memory available for a block buffer. See also HIMEM. 


LIST n--- 109 


List the ASCII symbolic contents of screen n on the current 
output device, setting SCR to contain n. n is unsigned. 


LIT --- n Cc 
Within a coion definition, LIT is automatically compiled 
before each 16-bit literal number’ encountered in input 


text. Later execution of LIT causes the contents of the 
following two bytes to be pushed to the stack. 
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LITERAL 8 ae I,215 


If compiling, then compile the stack value n as a 16-bit 
literal, which when later executed will leave n on the 
stack. 


LOAD i <<- 202 


Begin interpretation of screen n by making it the input 
stream; preserve the locators of the present input stream 
(from >IN and BLK). If interpretation is not terminated 
explicitly, it will be terminated when the input stream is 
exhausted. Control then returns to the input’ stream 
containing LOAD, determined by the input stream locators 
>IN and BLK. 


LOAD-BUFFERS nil n2 n3 --- 


The basic block-transfer word. Executes SAVE-BUFFERS, then 
EMPTY-BUFFERS. Read n3 consecutive blocks into memory, 
starting with block nl. As each block is read, renumber it 
consecutively, starting with number n2, and mark it as 
UPDATEd. A subsequent SAVE-BUFFERS will write these blocks 
to mass storage. An error message is displayed if n3 is 
larger than the current number of buffers (NBUF). 


LOOP I,C,124 


Increment the DO-LOOP index by one, terminating the loop if 
the new index is equal to or greater than the limit. The 
limit and index are signed numbers in  the_- range 
{-32 77/68. 232 Bs |e ke 


LGR --- 
Set Lo-Res full graphics mode. 

M* nl n2 --- d 
A mixed-magnitude arithmetic operation which leaves d, the 
product of nl times n2. 

M/ d nl --- n2 n3 
A mixed-magnitude arithmetic operator which leaves 
remainder n2 and quotient n3 from dividend d and divisor 
nl. The remainder takes its sign from the dividend. 

M/MOD udl un2 --- un3 ud4 
An unsigned mixed-magnitude arithmetic operation which 
leaves quotient ud4 and remainder un3 from a dividend udl 
and single divisor un2. 

MAX nl n2 --- n3 218 


Leave the greater of two numbers. "max 
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MAXBUF mim Bh 


Leave the maximum number of block buffers which would 
currently fit in memory. 


MIN nl n2 --- n3 127 
Leave the lesser of two numbers. "min" 

MIXED = 
Set mixed text and graphics mode. 

MOD nl n2 --- n3 104 


Divide nl by n2, leaving the remainder n3, with the same 
sign as nl. "mod" 


MODE --- addr 
A variable indicating the portability state of the system. 


If its value is zero, the system is in OPTIMIZER mode. 
Otherwise, it is in 79-STANDARD mode. See also appendix 


M. 

MON 
Exit to the system monitor, leaving a reentry to FORTH, if 
possible. Reenter with 803G or ctrl-Y (warm) or 800G 
(cold). 

MOVE addrl addr2 n --- 113 
Move the specified quantity n of 16-bit memory cells 
beginning at addrl into memory at addr2. The contents of 
addrl are moved first. If n is negative or zero, nothing 
is moved. 

MS n--- 
Delay for approximately n milliseconds. 

MSG --- 
System use only. 

NBUF --- n 
Leave the current number of disk buffers. 

NEGATE n--- --n 177 


Leave the two's complement of a number, ie, the difference 
of 0 less n. 
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NEXT --- addr 
Leave the address of address interpreter. The address 
interpreter uses the interpretive pointer IP to execute 
compiled FORTH definitions. It is not directly executed but 
is the return point for all code procedures. It acts by 
fetching the address pointed by IP, storing this value in 
register W. It then jumps to the address pointed to by the 
address pointed to in turn by W. W points to the code 
field of a definition which contains the address of the 
code which executes for that definition. This usage of 
indirect threaded code is a major contributor to the power, 
portability, and extensibility of FORTH. Locations of IP 
and W are computer specific. 

NFA addrl --- addr2 
Convert addrl,the parameter field address of a definition, 
to its name field address, addr2. 

NOT flagl --- flag2 165 
Reverse the boolean value of flagl. This is identical to 

NSW --- addr 
System use only. 

OF 
See CASE. 

ONERR 
Used in the form: 

ONERR <name> 

Ensures that subsequent ABORTs will resume execution with 
<name> rather than the normal outer interpreter. ONERR 
must be executed after the FORTH dictionary boots to be 
effective. 

OPTIMIZER -—- 
Set OPTIMIZER mode. See appendix M. 

OR nl n2 --- n3 223 
Leave the bitwise OR of two numbers. 

OVER nl n2 --- nl n2 nl 170 


Leave a copy of the second number on the stack. 
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PAD --- addr 226 


The address of a scratch area used to hold character 
strings for intermediate processing. The minimum capacity 
of PAD is 64 characters (addr through addr+63). 


PADDLE nl --- n2 


Read game paddle nl and leave its current value n2. 


PAUSE mene 


Execute KEY. If the next key typed is a carriage return, 
QUIT. Otherwise, discard the key and continue. 


PBUTTON n--- flag 
True if push-button n is pressed. 
PFA addrl --- addr2 


Convert addrl, the name field address of a definition, to 
its parameter field address, addr2. 


PICK nl --- n2 240 


Return the contents of the nl-th stack value, not counting 
nl itself. An error condition results for n less than 
one. 


2 PICK is equivalent to OVER. {1 .. n} 
POPTWO --- addr 


Leave the address of an inner interpreter entry point which 
pops two values from the stack. See appendix H. 


PR# n--- 


Apple II only: Select card slot n as the current character 
output device. 


PREV --- addr 
A variable containing the address of the block buffer most 
recently referenced. The UPDATE command marks this buffer 
to be later written to mass storage. 

PUSH --- addr 
Leave the address of a code sequence which pushes machine 
registers to the parameter stack and returns to NEXT. It 


is not directly executable, but is a FORTH reentry point 
after machine code. See appendix H. 
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QUERY 235 


Accept input of up to 80 characters (or until a "return") 
from the operator's terminal into the terminal input 
buffer. WORD may be used to accept text from this buffer 
as the input stream by setting >IN and BLK to zero. 


QUIT 211 


Clear the return stack, setting execution mode, and return 
control to the terminal. No message is given. 


R/W addr n flag --- 


The mass-storage read-write primitive. Read/write block n 
to/from block buffer at addr. Flag equals one for read, 
zero for write. R/W determines the location on mass 
storage, performs the read-write, and performs any error 


checking. 

R> --- n C,110 
Transfer n from the return stack to the data _ stack. 
"r-from" 

R@ “== C,228 


Copy the number on the top of the return stack to the data 
stack. "r-fetch" 


RA --- addr 


6502 use only: Leave the address used by CALL to _ loadP; 
then save the 6502 accumulator. 


RANDOM nl --- n2 
Leave a random number n2 whose value ranges from zero to nl 
minus 1. 

READY? --- flag 


Print ". READY(CR)?". Flag is true if the next key typed 
is an ASCII "return." 


RECONFIGURE -—= 


A self-prompting utility which allows you to change the 
number and location of the system disk drives. 


REFORMAT nl n2 --- 
A utility for converting source screens from version l 


format to version 2. Starting with screen nl, n2_ screens 
are converted. See appendix A. 
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REPEAT I,C,120 


ROLL 


ROT 


RP@ 


RP! 


RY 


S->D 


Used within a colon definiton in the form: 
BEGIN ... WHILE ... REPEAT 


At run time, REPEAT returns to just after the corresponding 
BEGIN. 


System use only. 

n--- 236 
Extract the nth stack value to the top of the stack, not 
counting n itself, moving the remaining values into the 
vacated position. An error condition results for n less 
than one. {1 .. 63} 

1 ROLL = null operation 

2 ROLL = SWAP 

3 ROLL = ROT 

nl n2 n3 --- n2 n3 nl 212 


Rotate the top three values, bringing the deepest to the 
top. "rote" 


--- addr 
Return the address of the return-stack position to the top 


of the parameter-stack, as it was before RP@ was executed. 
"r-p-fetch" 


A computer-dependent procedure to initialize the return 
stack pointer. 


“~~ addr 


6502 only: Leave the address used by CALL to load; then 
save the 6502 X-register. 


--- addr 


6502 only: Leave the address used by CALL to load; then 
save the 6502 Y-register. 


System use only. 
n--- d 


Sign extend a single number to form a double number. 
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S/DR =<—=' fi 
Leave the current number of sectors per disk drive on the 
stack. 

S/T --- n 
Leave the current number of sectors per disk track on the 
stack. 

SAVE 
Set FENCE to protect the current dictionary and save the 
dictionary on the mass storage device. The next 
programming session will begin with the dictionary most 
recently saved. 

SAVE-BUFFERS 221 
Write all blocks to mass storage that have been flagged as 
UPDATEd. An error condition results if mass-storage 
writing is not completed. 

SCR --- addr U,217 
Leave the address of a variable containing the number of 
the screen most recently listed. "s-c-r" {unsigned-number } 

SEED --- addr 
Leave the address of the variable used by RANDOM to compute 
the next random number in a sequence. 

SETFLASH == 
Set the Apple output mask to "flashing" text mode. All 
subsequent characters will be displayed in flashing text 
mode. 

SETINV -—= 
Set the Apple output mask to "inverse" text mode. All 
subsequent characters will be displayed in inverse text 
mode. 

SETNORM <= 
Set the Apple output mask to "normal" text mode. All 
subsequent characters will be displayed in normal text 
mode. 

SETSEED -—- 


Initialize the SEED variable. 
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SEIUP --- addr 
Leave the address of a machine-language subroutine utility 
which moves values from the parameter stack to a reserved 
memory area. See appendix H. 


SEVEC n --- addr 
An array containing CFA's of the screen environment words 
Called, respectively, by TINIT, TDONE, CH, CV, HOME, and 
BELL. 

SIGN n--- C,140 


Insert the ASCII - (minus sign) into the pictured numeric 
output string if n is negative. 


SKEWA 

System use only. 
SKEWB 

System use only. 
SL:DR 


System use only. 


SP! 
Initialize the stack pointer. "s-p-store" 
SP@ --- addr 214 
Return the address of the stack position to the top of the 
stack, as it was before SP@ was executed. "s-p-fetch" 
SPACE 232 
Transmit an ASCII "blank" to the current output device. 
SPACES n--- 231 
Transmit n spaces to the current output device. Take no 
action for n of zero or less. 
SQUISH nl n2 --- n3 
Leave number n3 on the stack, whose low-order byte is the 
low-order byte of nl, and whose high-order byte is the 
low-order byte of n2. 
STATE --- addr U,164 


Leave the address of the variable containing the 
compilation state. A non-zero content indicates 
compilation is occurring, but the value itself may be 
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installation dependent. 
SWAP nl n2 --- n2 nl 230 
Exchange the top two stack values. 
SWAPDROP nl n2 --- n2 
The equivalent of SWAP followed by DROP. 
TABLE n--- 
A defining word executed in the form: 
n TABLE <name> 
to create a dictionary entry for <name>. No bytes are 
ALLOTed in the parameter field. Elements are created with , 
("comma"). 
When executed later: 


n <name> 


will place the value of the nth element of the table on the 
stack. 


THEN I,C,161 
Used within a colon-definition in the form: 


IF eee ELSE eee THEN or 
IF ... THEN 


THEN is the point where execution resumes after ELSE or IF 
(when no ELSE is present). 


THRU nl n2 --- 


Successively LOAD screens nl through n2. These screens 
should not include the word -->. 


TIB --- addr 


A user variable containing the address of the terminal 
input buffer. 


TLOAD 
System use only. 
TOGGLE addr byte --- 


Complement the contents of addr by the bit pattern b. 
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TRAVERSE addrl n --- addr2 


Move across the name field of a variable-length name 
field. addrl is the address of either the length byte or 
the last letter. If n=l, the motion is toward high memory; 
if n=-l1, the motion is toward low memory. The addr2 
resulting is address of the other end of the name. 


TURNKEY 
Used in the form: 
TURNKEY <name> 
Ensures that the next time the dictionary is booted, 
execution will begin with the word <name>. TURNKEY is 
normally followed by a SAVE. See appendix J. 
TYPE addr n --- 222 


Transmit n characters beginning at addr to the current 
output device. No action takes place for n less than or 
equal to zero. 


TX tsi 
Execute HOME and set display to all text mode. 

U* unl un2 --- ud3 242 
Perform an unsigned multiplication of unl by un2, leaving 
the double-number product ud3. All values are _ unsigned. 
"u-times" 

U. un --- 106 
Display un converted according to BASE as an unsigned 
number in a free-field format with one trailing blank. 
"u-dot" 

U.R un n --- 216 


Print unsigned number un right-aligned in a field n 
characters wide. “u-dot-r" 


U/MOD udl un2 --- un3 un4 243 
Perform an unsigned division of double number udl by un2, 
leaving the remainder un3 and the quotient un4. All values 
are unsigned. “u-divide-mod" 

U< unl un2 --- flag 150 
Leave the flag representing the magnitude comparison of unl 


< un2 where unl and =un2 are treated as 16-bit unsigned 
integers. “u-less-than” 
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U2/ unl --- un2 


Perform an unsigned division of unl by 2. A right-shift is 
used for greater speed. 


UDN* udl un --- ud2 


Multiply udl by un, leaving the product ud2 on the stack. A 
32-bit intermediate product is used. 


UNTIL flag i ae I,C,237 


Within a colon definition, mark the end of a BEGIN-UNTIL 
loop, which will terminate based on a flag. If flag is 
true, the loop is terminated. If flag is false, execution 
returns to the first word after BEGIN. BEGIN-UNTIL 
structures may be nested. 


UPDATE 229 


Mark the most recently referenced block as modified. The 
block will subsequently be automatically transferred to 
mass storage should its memory buffer be needed for storage 
of a different block, or upon execution of SAVE-BUFFERS. 


V-LINK --- addr 


A user variable containing the address of a field in the 
definition of the most recently created vocabulary. All 
vocabulary names are linked by these fields to allow 
control for forgetting through multiple vocabularies. 


VARIABLE 227 
A defining word executed in the form: 
VARIABLE <name> 


to create a dictionary entry for <name> and allot two bytes 
for storage in the parameter field. The application must 
initialize the stored value. When <name> is later 
executed, it will place the storage address on the stack. 


VLINE nl n2 n3 --- 
Draw a Lo-Res vertical line from row nl to row n2 in column 
n3. The line will be drawn in the color last set by 
COLOR. 

VLIST 
List the names of the definitions in the context 
vocabulary. Typing any key will make the listing pause. 
Typing "“carrage return" will terminate the listing; any 
other key will restart listing. 


Note: a fancy VLIST is provided on the grandfather disk. 
It's format is: 
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PN # addr (cont) <name> <class> 


The P is displayed if the word is immediate, and the N if 
it is non-standard. # is the natural length of <name>. 
Both the PFA addr and the contents of the PFA (cont) are 
displayed. For constants and variables, this is the 
initial value. The <name> of the word and its defining 
<class> are displayed to the right. 


VOCABULARY 208 
A defining word execution in the form: 
VOCABULARY <name> 


to create (in the CURRENT vocabulary) a dictionary entry 
for <name> which specifies a new ordered list of word 
definitions. Subsequent execution of <name> will make it 
the CONTEXT vocabulary. When <name> becomes the CURRENT 
vocabulary (see DEFINITIONS), new definitions will be 
created in that list. 


In lieu of any further specification, new vocabularies 
"chain" to FORTH. That is, when a dictionary search 
through a vocabulary is exhausted, FORTH will be searched. 


WARM 
System use only. 
WHERE 


Used to locate an error which occurred while LOADing a 
screen. WHERE activates the EDITOR and positions the 
cursor after the location on the screen where the error 
occurred. 


WHILE flag ae I,C,149 
Used in a colon definition: 
BEGIN ... flag WHILE ... REPEAT 


Select conditional execution based on the flag. On a true 
flag, continue execution through to REPEAT, which then 
returns back to just after BEGIN. Ona false flag, skip 
execution to just after REPEAT, exiting the structure. 


WIDTH --- addr 


A user variable containing the maximum number of letters 
saved in the compilation of a definition's name. It must 
be 1 through 31, with a default value of 31. The name 
character count and its natural characters are saved, up to 
the value in WIDTH. The value may be changed at any time 
within the above limits. 
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WINDOW nl n2 n3 n4 --- 


Set the text display window to lie within the given 
parameters. The top is nl, the bottom is n2, the left 
column is n3, and the width is n4. See appendix G. 


WORD char --- addr 181 


Receive characters from the input steam until the non-zero 
delimiting character is encountered or the input stream is 
exhausted, ignoring leading delimiters. The characters are 
stored as a packed string with the character count in the 
first character position. The actual delimiter encountered 
(character or null) is stored at the end of the text but is 
not included in the _ count. If the input stream was 
exhausted as WORD is called, then a zero length will 
result. The address of the beginning of this packed string 
is left on the stack. 


XOR nl n2 --- n3 174 
Leave the bitwise exclusive-or of two 

XSTANDARD --- 
Reverse the "standard" sense of the last defined word. In 
other words, a standard word would become non-standard and 
vice-versa. See appendix M 


YES/NO --- flag 


Print " (Y/N)?". Flag is true if the next key entered is a 
vc fethad 


[ I,125 


End the compilation mode. The text from the input stream 
is subsequently executed. See ]. "left-bracket" 


[COMPILE] I,C,179 
Used in a colon definition in the form: 
[COMPILE] <name> 
Force compilation of the following word. This allows 
compilation of an IMMEDIATE word when it would otherwise be 
executed. "bracket-compile" 


] 126 


Set the compilation mode. The text from the input stream is 
subsequently compiled. See [. "“"right-bracket" 
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C.3 DOUBLE-NUMBER WORD SET 


2! qd addr --- 


Store din 4 consecutive bytes beginning at addr, as for a 
double number. "two-store" 


2@ addr --- d 
Leave on the stack the contents of the four consecutive 
bytes beginning at addr, as for a double number. 
"two-fetch" 
2CONSTANT d --- 
A defining word used in the form: 
d 2CONSTANT <name> 
to create a dictionary entry for <name>, leaving d in its 
Parameter field. When <name> is later executed, d will be 
left on the stack. "two-constant"” 
2DROP d --- 
Drop the top double number on the stack. “two-drop" 
2DUP d---dd 
Duplicate the top double number on the stack. "two-dup" 
20VER dl d2 --- dl d2 dl 


Leave a copy of the second double number on the. stack. 
"two-over” 


2ROT dl d2 d3 --- d2 d3 dl 


Rotate the third double number to the top of the stack. 
"two-rote" 


2SWAP dl d2 --- d2 dl 


Exchange the top two double numbers. on the stack. 
"two-swap” 


2VARIABLE 
A defining word used in the form: 
2VARIABLE <name> 
to create a dictionary entry of <name> and assign 4 bytes 
for storage in the parameter field. When <name> is later 


executed, it will leave the address of the first byte of 
its parameter field on the stack. "two-variable" 
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D+ 


DO 


D< 


DABS 


DMAX 


DMIN 


dl d2 --- d3 


Multiply dl by d2, leaving the product d3 on the stack. A 
32-bit intermediate product is used. 


dl d2 --- d3 241 
Leave the arithmetic sum of dl and d2. "d-plus" 
dl n --- d2 


Apply the sign of n to the double number dl, leaving it as 
d2. "d-plus-minus" 


dl d2 --- d3 
Subtract d2 from dl and leave the difference d3. "d-minus" 
d --- 246 
Display d converted according to BASE in a_ free-field 
format, with one trailing blank. Display the sign only if 
negative. "d-dot" 
dn --- 
Display d converted according to BASE, right aligned in an 
n-character field. Display the sign only if negative. 
"d-dot-r" 
d --- flag 
Leave true if d is zero. "d-zero-equals" 
dl d2 --- flag 244 
True if dl is less than d2. "d-less" 
dl d2 --- flag 
True if dl equals d2. "d-equal" 
dl --- d2 


Leave as a positive double number d2, the absolute value of 
a double number dl. {0..2,147,483,647} "d-abs" 


dl d2 --- d3 
Leave the larger of two double numbers. "d-max" 
dl d2 --- d3 


Leave the smaller of two double numbers. "d-min" 
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DN* dl n --- d2 


Multiply dl by n, leaving the product d2 on the stack. A 
32-bit intermediate product is used. 


DNEGATE d--- -d 245 


Leave the double number two's complement of a double 
number, ie, the difference 0 less d. "d-negate" 


DU< udl ud2 --- flag 


True if udl is less than ud2. Both numbers are_ unsigned. 
"d-u-less" 
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C.4 ASSEMBLER WORD SET 


CODE C,1,206 

Used in the form: 

: <mame> ... ;CODE 
Stop compilation and terminate a defining word <name>. 
ASSEMBLER becomes the CONTEXT vocabulary. When <name> is 
executed in the form: 

<name> <namex> 
to define the new <namex>, the execution address of <namex> 
will contain the address of the code sequence following the 


;CODE in <name>. Execution of any <namex> will cause this 
machine code sequence to be executed. "semi-colon-code" 


\SSEMBLER I,166 
Select assembler as the CONTEXT vocabulary. See appendix 
H. 

(ODE 111 


A defining word used in the form: 
CODE <name> ... END-CODE 
to create a dictionary entry for <name> to be defined by a 
following sequence of assembly language words. ASSEMBLER 
becomes the CONTEXT vocabulary. 
iIND-CODE 
Terminate a CODE definition, resetting the CONTEXT 


vocabulary to the CURRENT vocabulary. If no errors have 
occured, the CODE definition is made available for use. 
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This section is taken from the FORTH-79 Standards 
publication. The words of the required word set are grouped to 
show similar characteristics. No implementation requirements 
should be inferred from this grouping. 


Nucleus Words 


1 * */ */MOD + +! +loop - / 

/MOD O< O= O> 1+ I- 2+ 2- < 

= > >R ?DUP @ ABS AND begin C! 
C@ colon CMOVE constant create D+ 
D< DEPTH DNEGATE do does> 

DROP DUP else EXECUTE EXIT FILL I 
if J LEAVE literal loop MAX MIN 
MOD MOVE NEGATE NOT OR OVER PICK 
R> R@ repeat ROLL ROT semicolon 
SWAP then U* U/ U< until variable 
while XOR 


Note: lower-case entries refer only to the 
run-time code corresponding to a compiling word. 


Interpreter Words 


# #> #S ' ( -TRAILING . 

79-STANDARD <# >IN ? ABORT BASE BLK 
CONTEXT CONVERT COUNT CR CURRENT 
DECIMAL EMIT EXPECT FIND FORTH HERE 
HOLD KEY PAD QUERY QUIT SIGN SPACE 
SPACES TYPE U. WORD 


Compiler Words 


+LOOP , ." : 3 ALLOT BEGIN 

COMPILE CONSTANT CREATE DEFINITIONS DO 
DOES> ELSE FORGET IF IMMEDIATE 

LITERAL LOOP REPEAT STATE THEN UNTIL 
VARIABLE VOCABULARY WHILE [ [COMPILE] ] 


Device Words 


BLOCK BUFFER EMPTY-BUFFERS LIST 
LOAD SAVE-BUFFERS SCR UPDATE 
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* 
* 
* 
* 
* 


Stack Manipulation 


DUP 
DROP 


OVER 
SWAPDROP 


| 


ROT 
PICK 
ROLL 


0< 
0= 
0> 


Arithmetic and Logical 


+ 

D+ 
1+ 
l- 
2+ 
2- 
* 


/ 

MOD 
/MOD 
* /MOD 


Memory 


@ 
! 
cé@ 
Cl 


*/ 

U* 
U/MOD 
MAX 
MIN 
ABS 
NEGATE 
DNEGATE 
AND 
OR 
XOR 

2* 


? 


+! 
MOVE 
CMOVE 


Control Structures 


DO 
LOOP 
+LOOP 

I 

J 

LEAVE 
EXIT 
EXECUTE 


IF 
ELSE 
THEN 
BEGIN 
UNTIL 
END 
WHILE 
REPEAT 
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>R 2DUP 
R> 2DROP 


DEPTH 20VER 


D< 


NOT 


2/ 

>< 
TOGGLE 
HILO 
SQUISH 
U2/ 

M* 

M/ 
M/MOD 
S->D 
RANDOM 
SETSEED 


FILL 
<CMOVE 


ONERR 
TURNKEY 
CASE 

OF 
ENDOF 
ENDCASE 
GODO 
COLD 
WARM 
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WORDS BY FUNCTION 


Terminal Input-Output 


CR 

EMIT 
SPACE 
SPACES 
TYPE 
COUNT 
-~TRAILING 
KEY 
EXPECT 


QUERY CH 
WORD CV 
TDONE HOME 
TINIT IN# 
?KEY PR# 
BELL READY? 
BL TIB 

BS YES/NO 
ENCLOSE EMIT 


BASE ‘ <# 
DECIMAL U. # 

HEX PAD #S 
CONVERT oR HOLD 
PAD D.R HLD 
STRS #> 

Mass Storage Input-Output 

LIST SAVE-BUFFERS 

LOAD EMPTY-BUFFERS 

SCR LOAD-BUFFERS 

BLOCK BUFFERS 

THRU --> 

UPDATE #DRS 

BUFFER CATALOG 

B/BUF INDEX 

+BUF DOC 

Defining Words 

: VOCABULARY ARRAY 
: CREATE CARRAY 
VARIABLE DOES> TABLE 
CONSTANT : CODE CTABLE 
Vocabularies 

CONTEXT FIND "FORGET 
CURRENT ?FIND INFO 
DEFINITIONS ' VLIST 
V-LINK FORGET FORTH 
Compiler 

. COMPILE ?STACK 
c, [COMPILE] ?ERROR 
ALLOT 1CSP FENCE 
IMMEDIATE ?CSP WIDTH 
LITERAL ?PAIRS LIT 
STATE ?COMP LATEST 
[ ?EXEC 

] ?LOADING 
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L/S 
C/L 
C/SL 


R/W 
SAVE 
NBUF 
MAXBUF 
S/T 
B/DR 


CODE 


ASSEMBLER 
EDITOR 
EDIT 
WHERE 


E.0 


WORDS BY FUNCTION 


Miscellaneous 

( 7S 
HERE MS 

DP CALL 
PAD RX 
>IN RA 
BLK RY 
ABORT NEXT 
QUIT DESTRUCT 
79-STANDARD MON 
VLIST WHERE 
FENCE HIRES 
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NFA 
LFA 
CFA 
PFA 
RANDOM 
RP! 

SP! 

SP@ 
SMUDGE 
WIDTH 
ID. 


E.0 
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F.1 USING THE EDITOR 


To use the editor, simply type the number of the screen you 
intend to work with and the word EDIT; hit return and wait for 
the screen to appear. Suppose you want to edit screen 60, for 
example; first be sure that you are in decimal base, then just 
type the following: 


DECIMAL OK 
60 EDIT OK 


Now you are ready to make your changes. 


F.2 EDITING COMMANDS 


MicroMotion's FORTH-79 features a "screen editor"; unlike a 
"line editor," this allows you to move the cursor at will 
anywhere on the screen. The editing commands are very similar 
to Programma International's Apple P.I.E. If you are accustomed 
to a different editor, you may reassign these commands to more 
familiar keys using the word CMD (see Section F.3). 


F.2-l1 Cursor Movement Commands 


Most of these commands are accompanied by use of the 
control key on the left side of your keyboard. This key must be 
held down while the editing command key is pressed. In the 
following list of commands, this is indicated by use of a_ small 
c before the actual editing command. 


cF 
Move Right. Each time you type a cF, the cursor will 
move one character to the right on the same line. 
Nothing in the way will be destroyed. When you get to 
the end of the line, FORTH will not move on to the 
next line; it will simply stop. 


cS 
Move Left. This command works just like cF, except it 
moves left on the line, one character at a time. 


cc 
Move Down One Line. When you press cC, the cursor 
will move down one line from wherever it is on the 
line at the time. Like other cursor-moving commands, 
it will not destroy characters in its path. You can 
use cC in rapid succession to move down several 
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lines. When you get to end of the screen, the cursor 
will simply stop. 


cE 
Move Up One Line. This command works just like cC, 
except that it moves up one line at a time. 

cG 
Tab Right. Pressing cG will move the cursor to the 
right five spaces all at once. When you get to the 
rightmost end of the screen, the cursor will stop. 

cA 
Tab Left. As you would expect, this command will move 
the cursor five space to the left. 

cx 
Tab Down. Press cX and the cursor will move down five 
lines. 

cW 
Tab Up. The command cW will move the cursor five 
lines up on the screen. 

cV 
Move Ahead One Screen. A cV command will move _ the 
cursor ahead to the beginning of the next screen. 

cR 
Move Back One _ Screen. A cR command will move the 
cursor back to the beginning of the previous screen. 

<-- or cH 
Backspace. This command moves the cursor to the left 
and then replaces the character under the cursor with 
a blank. You can avoid erasing characters with the cS 
command. 

--> 
Copy Character. This key operates exactly the same in 
the editor mode and is equivalent to cF. 

cB 
Beginning/Ending of Line. This command alternately 
moves the cursor to the beginning and end of the line 
the cursor is on. The first time you type a cB, the 
cursor will move to the beginning of the current line, 
the second time to the end, and so forth. 

cT 
Toggle. If your video display is less than 64 
characters/line, you can use cT to toggle between the 
right and left halves of the text. 

cD 


Doggle. This command toggles the cursor between the 
upper and lower left-hand corners of the screen. 
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E.2.2 Text Manipulation Commands 


cP 


cJ 


Insert Characters. This command will allow you to 
insert one or more characters starting at the location 
of the cursor. When you press cP, the insert message 
will appear on the top or bottom of the screen to let 
you know the editor is ready to insert. You can now 
type new material; FORTH will move the old material 
over to make room for it so that nothing is lost. 
When you get close to the end of the line, you will 
hear a beep to warn you that the last character on the 
line will be lost if you enter another character. 
Pressing cP again will get you out of the insert 
mode. 


Gobble. This command will remove characters one at a 
time starting at the present location of the cursor 
and close up the old material to fill in the space. 
The command cJ can be used repeatedly to take out 
several words or phrases. If you need to take out 
whole lines, see shift-cN below. 


shift-cN 


cI 


Join Lines. Characters under and to the right of the 
cursor are replaced with the line below the current 
line. The following lines are moved upward. If there 
is insufficient space at the end of the current line, 
the bell sounds and no action is taken. If you want 
to delete a line, first position the cursor at the 
left of the line and then type shift-cN. 


Split Lines. When you press cI, the part of the 
current line under and to the right of the cursor will 
be moved to the following line. The material 
Originally there, plus everything below it, will be 
moved down one line. The current line to the right of 
the cursor is now blank. If there is insufficient 
space, that is, if the bottom line on the screen has 
any characters in it, the bell sounds and no action is 
taken. If you want to open up a line, first position 
the cursor at the left of the line, and then type cI. 


When you want to move and/or copy lines of your program, this 


next 


of commands (cK, cL, cO, cY, cQ, and cZ) is 


particularly useful. 


cK 


Delete and Push Current Line. The command cK will 
delete the line that the cursor is now sitting on, but 
instead of destroying the line it will push it onto a 
temporary line-stack for future use. If the temporary 
line-stack is full, the bell sounds and no action is 
taken. Many lines, even entire screens, can be pushed 
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cL 


cO 


cY 


cQ 


cZ 
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by repeating this command. 


Copy and Push Current Line. This command differs from 
cK in that the line in the current program will not be 
deleted. Instead, a copy will be pushed onto a 
temporary line-stack for possible use elsewhere. If 
the temporary line-stack is full, the bell sounds and 
no action is’ taken. Many lines can be pushed by 
repeating this command. 


Pop Line. When you decide where the lines in the 
temporary line-stack will be placed (whether elsewhere 
on the screen or on another screen entirely), you can 
pop them and insert them in the new location with c0O. 
Pressing cO once will open up one new line, moving 
everything else down accordingly. If the temporary 
line-stack is empty or the bottom line on the screen 
has characters in it, the bell sounds and no action is 
taken. Whole blocks of screen material can be moved 
this way, even from one screen to another (with cR and 
cV). Leaving and reentering the editor will clear the 
temporary line-stack. Lines are stored in LIFO order, 
that is, the first line inserted will be the last line 
pushed. 


This command clears the temporary line-stack used by 
cK, cL, and co. 


Save-Buffers. This command will make sure that all 
screens that you have modified are written to the 
disk. It is a good idea to to use cQ frequently in 
case there is an unexpected failure. If you merely 
examine your screen and/or move the cursor around it 
without altering anything, FORTH knows that it is not 
necessary to update the screen on the disk. This 
command does not take you out of the editor. 


Restore Screen. It will occasionally happen that you 
want to experiment with a screen you have already 
written; if you don't like the experimentation, you 
might want to get the old screen back. In that’ case, 
simply press cZ, and the old screen will be updated 
from the disk, destroying the experimental screen. 


F.2-3 Other Commands 


shift-cP 


Exit Editor. When you want to stop editing and get 
back into the normal keyboard input mode, hold down 
the shift key at the same time that you type ae cP. 
You are now back in FORTH and no longer have access to 
the special editing commands. Remember that if you 
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want to get back into the editor mode, you only need 
to type the number of the screen plus the word EDIT. 


shift-cM 
Exit Editor and Load. You can also exit the editor 
(shift-cP) and LOAD the current screen with the single 
command, shift-cM. This command does not perform a 
Save-Buffers (cQ). 


F.3 Changing Editor Commands 


You may redefine any of the editing control keys. First, 
type the word CMD into your dictionary: 


: CMD ( ASCII <COMMAND-WORD> --- ) 
FIND DUP 0= 0 ?ERROR SWAP EDITOR CMDADR ! ; 


Push the ASCII value of the control key you want to change onto 
the stack, followed by CMD and the name of the command word (see 
chart below). Only the first 32 (0 through 1F hex) ASCII values 
may be used. For example, if you wish to move the cursor to the 
right with a cA (ASCII 1), type: 


1 CMD CRIGHT 
You can use your current editor to type a list of command 
changes into a screen. Loading this screen then reorders’ the 


editor commands. To save dictionary space, you can FORGET CMD 
when the changes are complete. 
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COMMAND WORD 


CRIGHT 
CLEFT 
CUP 
CDOWN 
TRIGHT 
TLEFT 
TUP 
TDOWN 
==> 
C<== 
DOGGLE 
FLIP 
CCR 
FWD 
REV 
CDEL 
INSTOG 
SPLIT 
JOIN 
LMOVE 
LCOPY 
LPOP 
TLCLR 
SCRFLUSH 
RENEW 
BYE 
BLKLOAD 
SCLR 
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TABLE F.1 EDITOR COMMANDS 
ACTION 


Cursor right 

Cursor left 

Cursor up 

Cursor down 

Tab right 

Tab left 

Tab up 

Tab down 

Begin/end of line 
Backspace 

Cursor upper/lower left 
Right/left halves of screen 
Carriage return (control-M) 
Edit next screen 

Edit previous screen 
Gobble 

Insert/Replace mode 

Line split/insert 

Line join/delete 

Line delete and push 

Line copy and push 

Line pop 

Clear temporary line-stack 
Save-buffers 

Restore screen from disk 
Exit editor 

Exit editor and LOAD 

Clear screen 
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* APPLE II UTILITIES 
* 
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The Apple II version of MicroMotion FORTH has_ several 
commands to make it easy for you to use the special features of 
your Apple II computer. You can use these commands to 
manipulate the text screen, create graphic displays, read the 
game paddles and buttons, call machine language subroutines, and 
so forth. Some of these commands must be LOADed initially from 
riba provided on the grandfather disk. See appendix A.1 for 

etails. 


G-l1 RECOVERING FROM RESET 


REKKKEKKEKKEKEKEEKEEKEKEEEEKEKEEEKEEKEEKEEREEEKEK 
* * 


* To recover from a RESET, type 803G * 
* 


* from the Apple monitor. 
* * 
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You can use RESET for many purposes, including escaping infinite 
loops and other programming problems. If you have an autostart 
ROM, RESET will return you to FORTH. Otherwise, typing 800G 
executes the FORTH warmstart. Nothing in the buffers will be 
altered in any way by the warmstart. If you suspect the 
dictionary has been damaged, do not SAVE it. Instead, save the 
buffers with SAVE-BUFFERS and reboot the disk. 


After a warmstart, control normally passes to the FORTH 
interpreter unless redirected with an ONERR- command. See 
appendix J for details. 


G.2 TEXT WINDOW MANIPULATION 
You can position the input cursor anywhere on the text 
window with the commands CV ("cursor vertical") and CH ("cursor 
horizontal"). For example: 
12 Cv 5 CH 


This moves the cursor to the 12th row and 5th column. Remember 
that rows are numbered 0 to 23, starting at the top. Columns 
are numbered 0 to 39, starting at the left. 
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The command HOME puts’ the cursor in the upper left-hand 
corner of the text window and clears the window. The dimensions 
of the window can be altered with the command WINDOW. The 
arguments required by WINDOW are, in order: the top row, the 
bottom row-plus-one, the left column, and the horizontal width. 
For example: 


10 18 5 15 WINDOW 


This creates a window which runs horizontally from column 5 to 
column 19 (5+15-1) and vertically from row 10 to row 17 (18-1). 


The commands SETNORM, SETINV, and SETFLASH set flags in the 
Apple output subroutines. SETINV causes all subsequent 
characters to be displayed on the text screen in inverse video. 
SETFLASH causes characters to appear in flashing video. SETNORM 
restores the normal video output without affecting characters 
already displayed. 


G.3 USING GRAPHICS 


G.3.1 Lo-Res Graphics 


The text screen can be converted to a Lo-Res 
(low-resolution) graphics screen with the command LGR. Each of 
the 40 x 48 plotting positions can be displayed as a small 
rectangle in one of 16 colors. You can also use the command 
MIXED, which leaves a text window at the bottom four lines. 
This reduces the resolution to 40 x 40 but lets you see what you 
are typing. 


The color is selected with the command COLOR, which takes a 
number from 0 to 15 as aé_ color. The Apple utility screens 
include constants whose values are equal to the more common 
colors: 

CONSTANT BLACK 
CONSTANT MAGENTA 
CONSTANT D-BLUE 
CONSTANT D-GREEN 
CONSTANT BROWN 
CONSTANT ORANGE 
CONSTANT YELLOW 
CONSTANT WHITE 


UWWORNE © 


1 
1 
To plot a point (small rectangle) on the Lo-Res display, first 
set the color: 


MIXED 
YELLOW COLOR _OK 


Next, push the xX and Y coordinates on the stack and use the 
command PLOT: 


10 12 PLOT OK 
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A yellow spot will appear on the screen at column 10, row 
12--provided you have a color monitor. Otherwise a white spot 
will appear. 


You can inspect the color of any spot you have plotted with 
the command SCRN. For example: 


10 12 SCRN . 13 OK ( YELLOW ) 


SCRN tells you that the spot at row 10 column 12 has the value 
yellow. 


You can also draw horizontal and vertical lines with the 
commands HLINE and VLINE. HLINE requires the starting column, 
ending column, and row (in that order). VLINE requires the 
starting row, ending row, and column. To draw a small square, 


type: 


10 15 10 HLINE 10 15 15 HLINE OK 
10 15 10 VLINE 10 15 15 VLINE OK 


Since COLOR is still set to yellow, the square will be yellow. 
To return to the text screen, simply type TX. 


G.3.2 Hi-Res Graphics 


The constant HIRES leaves the address of the Apple 
high-resolution graphics page on the stack. (High-resolution 
plotting routines are are available as an option. Contact 
MicroMotion for details.) 


The graphics page is actually a reserved memory area 
already included in your dictionary, starting at hexadecimal 
address 2000. You may use this area for any programming 
purpose, provided you do not wish to use it for high-resolution 
graphics. For example, you can treat it as an 8K array of 
bytes. The contents of the third byte (from zero) are put on 
the stack by the FORTH expression HIRES 2 + C@. Other programs 
may freely use the graphics page. When a dictionary is SAVEd, 
the contents of the graphics page are also saved. 


G.4 USING GAME INPUT/OUTPUT 


MicroMotion FORTH has two commands (PADDLE and PBUTTON) 
that you can use to read the Apple game I/O interfaces. To read 
the game paddle, simply push the number of the paddle on the 
stack and type PADDLE. PADDLE leaves the current setting of the 
game paddle (a number from 0 to 255) on the stack: 


0 PADDLE . 
1 PADDLE . IK 


PBUTTON reads one of the three push buttons, leaving a true if 
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the button is pressed and a false otherwise: 


0 PBUTTON . 0 OK 
1 PBUTTON . 1 OK ( PRESSED ) 
2 PBUTTON . 0 OK 


You can easily write other FORTH words to set the user _ strobe, 
click the loudspeaker, and so forth with the commands given 
below. 


G-5 CALLING MACHINE-LANGUAGE SUBROUTINES 


The Apple monitor contains many useful machine-language 
subroutines. Intelligent peripheral cards and vendor software 
packages may also contain machine-language subroutines. To use 
a machine-language subroutine, you generally need to set up the 
three major 6502 machine registers: RA, RX, and RY. When 
control returns from the subroutine, you may also need to 
examine the contents of these three registers. 


MicroMotion FORTH provides three one-byte memory locations 
which are loaded into the machine registers when you call a 
subroutine and which are copied from the machine registers on 
return. These three locations are given by the constants RA, 
RX, and RY. The actual call is done with the command CALL. 


For example, suppose you wish to know the value of the 
first game paddle. The Apple user's manual tells you to load 
the number of this paddle (0) into the X-register (RX) and call 
hexadecimal address FBIE. On return, the value of the paddle 
will be in the Y-register (RY). This is what you should type: 


HEX O RX ! FBILE CALL RY C@ 
In fact, the definition of PADDLE is: 


: PADDLE ( #PAD[[0-3 --> #SETTING ) 
RX C! FB1E CALL RY C@ ; 


Notice that CALL calls the subroutine whose address is on top of 


the stack. More details on calling and using machine-language 
Subroutines can be found in appendix H. 
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MicroMotion FORTH-79 features an assembler vocabulary to 
create machine code definitions for time-critical procedures. It 
is assumed that you have some knowledge of 6502 assembly 
language programming and the internal structure of MicroMotion 
FORTH-79. A good tutorial on the subject is "Practical 
microcomputer programming: The 6502," by W.J. Weller (Northern 
Technology Books, 1980). For information about the internal 
structure of MicroMotion FORTH-79, read appendix K. 


H.l A SIMPLE ASSEMBLER DEFINITION 


An example of a simple word definition written with both a 
conventional assembler and with the FORTH assembler for 
comparison is that of CMOVE, CMOVE requires three arguments on 
the stack: a from-address (third item), a to-address (second 
item), and a byte-count (top item). Byte-count bytes are moved 
from the from-address to the to-address, starting with the 
leftmost byte: 

CONVENTIONAL ASSEMBLER FORTH ASSEMBLER 
HEX 
86C CONSTANT SETUP 
( CMOVE - GENERAL 


SETUP EQU $86C 
3 CMOVE - GENERAL 


? MOVE UTILITY MOVE UTILITY ) 

CMOVE LDA #3 CODE CMOVE 3 # LDA, 
JSR SETUP SETUP JSR, 

LOOP CPY N 1 L: N CPY, 
BNE MVBYTE 2 L# BNE, 
DEC N+1 N 1+ DEC, 
BPL MVBYTE 2 L# BPL, 
JMP NEXT NEXT JMP, 

MVBYTE LDA (N+4) ,Y 2 L: N 4 + )Y LDA, 
STA (N+2) ,Y N 2 + )Y¥ STA, 
INY INY, 
BEQ BMPCNT 3 L# BEQ, 
JMP LOOP 1 L# BNE, 

BMPCNT INC N+5 3 L: N 5 + INC, 
INC N+3 N 3 + INC, 
JMP LOOP 1 L# BNE, 1 L# BEQ, 
END END-CODE 
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Although the FORTH assembler definition looks like a 
Standard assembly code definition, each word encountered is 
interpreted rather than compiled. Some assembler words, such as 
)Y, set an address-mode flag; others (such as LDA, and DEC,) 
store machine instructions in the dictionary. Because FORTH is 
interpreting instead of compiling, you can use the full power of 
FORTH to do address calculations for operands. It is important 
to understand the difference between interpreting an ASSEMBLER 
opcode word and executing the machine instruction it creates. 
At "assembly time," an assembler opcode word stores a machine 
instruction in the dictionary. At "run time," the machine 
instructions are executed. 


H.-2 BEGINNING AN ASSEMBLER DEFINITION 


An assembly definition begins with the assembler word CODE 
followed by the name of the word being defined. 


CODE CMOVE 


When CODE is executed, it creates a dictionary entry for CMOVE 
in the CURRENT vocabulary. The machine instructions which follow 
will be placed into the CMOVE parameter field. When CMOVE is 
later executed, the machine code in the parameter field will be 
executed. 


CODE also sets CONTEXT to ASSEMBLER. Now when FORTH 
searches for a word in the dictionary, it will first search 
through the ASSEMBLER vocabulary. 


H.3 INSTRUCTION FORMAT 


Instructions in this assembler are specified in the 
following order: 


operand address-mode opcode 
For example, 
COUNT ,X INC, 


The operand is COUNT, the address-mode is ,X , and the opcode is 
INC, . 


H.3.1 Operands and Labels 


If an instruction opcode requires an operand, the operand 
must be pushed onto the parameter stack before the opcode is 
encountered. An operand can be calculated using any FORTH 
operations that leave a value on the stack. For example, in 
CMOVE, the operand for the opcode DEC, is calculated by adding 
one to the constant N: 


INSTRUCTION FORMAT H.3 


6502 ASSEMBLER Lai 


N 1+ DEC, 


Conventional assemblers use labels to reference data 
locations and to act as targets for branching. In the example 
above, the value of the constant N is an address in page zero. 
The number one is added to this address and the result is used 
as an operand for the DEC, opcode. Since a FORTH variable 
pushes an address onto the stack, you can load a register with 
the data in the variable like this: 


AMOUNT LDA, 


AMOUNT is a variable. The address left on the stack by AMOUNT 
is used as the argument for LDA,. 


Address operands can also be created with the word ' 
("tick"). 


' CMOVE JSR, 


The address of the parameter field of the machine code _ routine 
CMOVE is pushed on the stack as an operand for the JSR, opcode. 


H.3.2 Address-modes 


The 6502 has 13 address-modes. Some of these address-—modes 
are implied by the opcode. For example, INY has the "implied" 
address-mode of the machine register Y. Because of this, the 
assembler only needs seven words to specify all 13 
address-modes: 


WORD ADDRESS-MODE 


oA Accumulator. 

ft Immediate. 

7X Page zero and absolute, indexed by X register. 
rX Page zero and absolute, indexed by Y register. 
) Absolute indirect. 

X) Page zero indexed by X , indirect. 

)Y Page zero indirect, indexed by Y. 


If no address-mode is specified for an instruction, it is 
assumed to be either page zero or absolute, depending on the 
value of the operand. Address-mode words do not use the 
parameter stack. Instead, they set a flag ( ADRMODE ) to select 
the address-mode. 


H.3.3 Opcodes 


Each assembler instruction ends with an opcode word. When 
the opcode word is executed, it takes its operand, if any, from 
the stack and its address-mode from ADRMODE. The opcode then 
tries to generate a valid machine instruction in the 
dictionary. Notice that all opcode words end with a , 
("comma"). This is to remind you that instructions are 
functionally independent and that they store code in the 
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dictionary. It also prevents opcodes such as ADC and DEC from 
being interpreted as hex values. 


H.4 ENDING AN ASSEMBLER DEFINITION 


Ending an assembler definition requires two actions: the 
assembly-time action and the run time action. 


The word END-CODE ends the assembly-time definition. 
END-CODE sets the CONTEXT vocabulary to the CURRENT vocabulary 
and checks to see that nothing is left on the stack by mistake. 


During run-time, the machine code must have some way of 
returning control to the FORTH address interpreter. There are 
several ways for the run-time code to exit. If you were using a 
conventional assembler, you would usually exit with an RTS 
instruction. This is correct if the code was originally called 
by a JSR instruction. However, most CODE definitions (such as 
CMOVE) are not called by a JSR instruction. Instead, they are 
executed under control of the FORTH address intrepreter. These 
words must exit with a JMP to the address interpreter. The 
constant NEXT puts the return address of the address interpreter 
on the stack: 


NEXT JMP, 


For example, here is a CODE routine that does nothing at all 
except exit: 


CODE TASK NEXT JMP, END-CODE 


Typing TASK will execute the JMP instruction, which in turn will 
branch back to the address intrepreter to execute the next 
word. 


H.5 STACKS, REGISTERS, AND PAGE ZERO 


A CODE definition often needs to access run-time values on 
the parameter stack or the return stack. 


H.-5.1 The Parameter Stack 


In this section, we will refer to the latest value on the 
Parameter stack as the "bottom" of the stack. The parameter 
stack used in MicroMotion FORTH actually builds downwards rather 
than upwards. 


The assembler word BOT sets up both the operand and the 
address mode to reference the bottom value on the parameter 
stack. Each 16-bit value on the stack is stored according to 
the 6502 convention of placing the high-order byte above the 
low-order byte in memory. The X-register is used as the 
parameter stack pointer. It points to the low-order byte of the 
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bottom value on the stack. The definition of BOT is: 
: BOT 0 XxX 3 


BOT places the operand zero on the stack and sets the address 
mode to “indexed by X." Any opcode that follows will use these 
arguments. 


For example, you can load the accumulator with the 
low-order byte of the bottom value on the parameter stack this 
way: 


BOT LDA, 


To load the Y-register with the high-order byte of the same 
value, you can use: 


BOT 1+ LDY, 


To reference the second 16-bit value on the parameter stack, use 
the word SEC. Its definition is: 


: SEC 2 ,X ; 


H.5.2 The Return Stack 


MicroMotion FORTH-79 uses the 6502 machine stack for its 
return stack. This stack is located in page 1 ($100-1FF). It 
starts at S$1FE and moves downward. There is no check for 
wraparound. The 6502 register S (stack) points to the next 
available byte just below the bottom of the stack. 


There are many ways to access data on the return stack. You 
can get the bottom two bytes this way: 


PLA, TAY, PLA, 


This removes the low-order byte and puts it in the Y-register. 
The high-order byte is removed and put in the accumulator. 


If you want to use data deeper in the return stack without 
disturbing the data on top, you should first save the X-register 
at XSAVE (a scratch area provided in page zero). Next, transfer 
the S-register to the X-register. Now the data you want can be 
indexed by the X-register directly. Finally, restore the 
X-register. The code to load the fifth byte of data from the 
return stack would look like this: 


XSAVE STX, TSX, 106 ,X LDA, ... XSAVE LDX, 


Here is the definition of the FORTH word J, which pushes the 
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index of the second-outermost loop on the parameter stack: 


CODE J 
XSAVE STX, TSX, 
105 ,X LDY, 106 ,X LDA, 
XSAVE LDX, DEX, DEX, 
BOT 1+ STA, TYA, BOT STA, 
NEXT JMP, END-CODE 


SAVE X-REGISTER ) 

LOAD LOOP INDEX ) 
RESTORE X & PUSH... ) 
.+.e INDEX ON PARM STACK ) 
RETURN ) 


H.5-3 6502 CPU Registers 


When you are writing a CODE definition, it is important to 
consider how each machine register is being used. Here is a 
list of the initial conditions of each register when a CODE 
definition is executed: 


REGISTER DESCRIPTION 
A General purpose: initially undefined. 


X Parameter stack pointer: points to the 
low-order byte of the last value pushed on 
the stack relative to address 0000. 


bs General purpose: initially zero. 


s Return stack pointer: points to next free byte 
on return stack relative to address $0100. 


P Processor status: initially set to binary 
arithmetic mode. Interrupts disabled. 
Must be returned in these modes. 


H.5-4 FORTH Pseudo-Registers 


The MicroMotion FORTH address interpreter uses several page 
zero pseudo-registers which you might wish to examine or 
change: 


CONSTANT PSEUDO-REGISTER 
NAME DESCRIPTION 


IP Interpretive pointer: contains the address 
of the next FORTH address that will be 
executed by the address interpreter when 
control is returned via NEXT. 


W Contains the address of the code field of the 
dictionary definition currently being 
interpreted. The code field of a word always 
contains a pointer to machine code. 

There is an indirect jump opcode ($6C) at W-l. 
A jump to W-1 will jump to this machine code. 


XSAVE A temporary storage location which you can use 
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to save the X-register. 


H.5-5 Page Zero Usage 


You may need to use several locations of your own in page 
zero. You can use a scratch area called the "N area": 


N A temporary storage area in page zero. 
You may use addresses from N-1 to N+19. 


The N area is usually used to hold pointers for indirect 
addressing. MicroMotion FORTH-79 uses most of page zero for its 
parameter stack. If you are interfacing to software that 
requires a large area of page zero, you should create a 
Subroutine which saves this area of page zero, calls the 
software, and restores this area of page zero. 


H.5.6 Stack Transfer Routines 


The utility subroutine SETUP removes 16-bit values from the 
parameter stack and transfers them to the N area. SETUP is not 
a FORTH word and must be called by a JSR, instruction from 
within a CODE definition. To use SETUP, load the accumulator 
with the number of 16-bit values to transfer, then use JSR, to 
SETUP. Since the N area is only 21 bytes long, the accumulator 
may only move up to 10 16-bit values. Here is how to move two 
16-bit values from the parameter stack to the N area: 


2 # LDA, SETUP JSR, 


The bytes are transferred in this order: 


PARAMETER 
STACK N AREA 
SEC+1l --> N+3 
SEC --> N+2 
BOT+1 --> N+l 
BOT --> N 


Remember that these bytes are removed from the parameter stack. 


Four utility subroutines are included which allow you to 
exit a CODE definition while simultaneously popping or pushing 
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arguments on the parameter stack: 
CONSTANT DESCRIPTION 


POP Discards one 16-bit value from the parameter 
stack. 


POPTWO Discards two 16-bit values from the parameter 
stack. 


PUT Replaces the bottom 16-bit value on the 
Parameter stack. The accumulator is stored in 
the high-order byte. The low-order byte is 
popped from the 6502 return stack. 


PUSH Pushes a 16-bit value on the parameter stack. 
The accumulator is stored in the 
high-order byte. The low-order byte is popped 
from the 6502 return stack. 


All of the above routines jump to NEXT. 


For example, you can define a word to push the number 3 on the 
stack this way: 


CODE THREE (<--> 3 ) 
3 # LDA, PHA, 
TYA, ( INITIALLY 0 ) 


PUSH JMP, END-CODE 


H.6 ASSEMBLER FLOW OF CONTROL 
H.6.1 Conditional Branching 
The MicroMotion FORTH-79 version 2 assembler provides 16 
numeric local labels for conditional branching. These labels 
are unique for each CODE word and may be forward-referenced. 
The syntax for branching to a label is: 
Number L# Opcode 


where opcode can be any of the 6502 conditional branches: BCC, 
BCS, BEQ, BMI, BNE, BPL, BVC, or BVS. 


The syntax for creating a label is: 


Number L: Instruction 
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For example, here is the code for CMOVE: 


CODE CMOVE 

3 # LDA, SETUP JSR, 

N 1+ LDA, 1 L# BMI, 

2 L: N CPY, 3 L# BNE, 

N 1+ DEC, 3 L# BPL, 

1 L: NEXT JMP, ( Exit ) 

3 L: N 4 + )¥ LDA, N 2+ )Y STA, 

INY, 2 L# BNE, 

N 5 + INC, N 3 + INC, 

2 L# BNE, 2 L# BEQ, ( ALWAYS TAKEN ) 
END-CODE 


Note: The structured conditionals of version 1 are described 
below. They may be LOADed from the version 2 grandfather disk 
(see appendix A). 


H.6.2 Structured Conditionals 


Conventional assemblers use labels as targets for 
branching. The MicroMotion FORTH-79 version 1 assembler is 
structured and does not use labels as branch targets. Instead, 
it uses control structures that are similar to the FORTH flow of 
control structures: 


IF, eee THEN, 

IF, «.- ELSE, ... THEN, 
BEGIN, ... AGAIN, 

BEGIN, ... UNTIL, 

BEGIN, ... WHILE, ... REPEAT, 


There are two differences (besides the comma) between FORTH and 
assembler control words. First, most assembler control words 
store machine code in the dictionary instead of FORTH code. 
Second, run-time flow of control is determined by flag bits in 
the 6502 status register. To select which status bits are to be 
tested, five conditional selector words are provided: 


O= O< CS VS NOT 


These are words in the assembler vocabulary and should not be 
confused with words having the same name in the FORTH 
vocabulary. A conditional selector word is used just before a 
branching word, such as: 


0= IF, eos THEN, 


The conditional selector tells the branching word what type of 
branch instruction to generate. In this case a BNE instruction 
branches over some intervening code to the THEN, . Here is a 


ASSEMBLER FLOW OF CONTROL H.6 


6502 ASSEMBLER 178 


list of all possible conditional selectors: 


CONDITIONAL 6502 PROCESSOR 
SELECTORS STATUS BITS DESCRIPTION 


NZCYV 
0< L less than zero 
0< NOT 0 not less than zero 
= 1 equal to zero 
= NOT 0 not equal to zero 
cs 1 carry set 
CS NOT 0 Carry clear 
vs . overflow set 
VS NOT 0 overflow clear 


The assembler command IF, is used to select alternate 
execution paths. For example: 


CODE 1+ 
BOT INC, 0= ( INCREMENT LOW BYTE ) 
IF, BOT 1+ INC, ( INCREMENT HIGH BYTE IF Z=1 ) 


THEN, NEXT JMP, END-CODE ( RETURN ) 


First, the low-order byte on the parameter stack is 
incremented. If the result is zero we must increment the 
high-order byte. At assembly time, the conditional selector 0= 
puts a flag on the parameter stack. The IF, takes this flag and 
generates a BNE instruction. Next the high-order byte is 
incremented. At assembly time, the THEN, word fixes up the BNE 
instruction to branch over the increment instruction. 


An optional ELSE, execution path is also possible. The 
following word ?TERMINAL reads the keyboard and returns a 
boolean value indicating whether a key has been pressed: 


CODE ?TERMINAL 
cooo BIT, O0< ( GET KEYBOARD STATUS ) 
IF, 1 # LDA, ( A-register=1 ) 
ELSE, TYA, ( A-register=0 ) 
THEN, C010 STA, ( CLEAR KEYBOARD STROBE ) 
PHA, TYA, ( GET READY FOR PUSH ) 
( 


PUSH JMP, END-CODE PUSH AND RETURN ) 


If the assembler tries to generate a relative branch 
farther than +127 or -128, the error message "CODE TOO BIG" will 
be displayed. 

H.6.3 Looping 


The assembler provides three types of loop structures. 
These are: 
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BEGIN, ... UNTIL, 
BEGIN, ... WHILE, ... REPEAT, 
BEGIN, ... AGAIN, 


The first two strongly resemble their FORTH counterparts. The 
third is an infinite loop. 


The BEGIN, ... UNTIL, loop will repeat until the condition 
which precedes the UNTIL, is met. The loop’ will then 
terminate. The following word WAITKEY waits in a loop until a 
key is pressed: 


CODE WAITKEY 
BEGIN, C000 LDA, 0< ( LOOP UNTIL KEY PRESSED ) 
UNTIL, C010 STA, ( CLEAR KEYBOARD STROBE ) 
NEXT JMP, END-CODE ( RETURN ) 


The BEGIN, ... WHILE, ... REPEAT, loop will repeat until 
the condition which precedes the WHILE, is not met. The loop 
will then terminate. The following short machine-code 
definition illustrates this: 


REPEAT, TYA, PHA, 0 # LDA, 
PUSH JMP, END-CODE 


GET READY TO PUSH ) 
PUSH & RETURN ) 


CODE INLEN ( GET LENGTH OF MSG ) 
BEGIN, INBUF ,Y LDA, ( LOAD A CHARACTER ) 
13 # CMP, 0= ( I8 I7 Cre 2 
WHILE, INY, ( IF NOT, INCREMENT Y ) 
( 
( 


The assembler also includes an infinite loop structure: 


BEGIN, ... AGAIN, 


Warning: This loop will never end unless there is a NEXT JMP, 
(or RTS,) somewhere within the loop. For an example of this type 
of loop, refer back to the CMOVE definition (section H.1). 


H.6.4 Nesting 


Branching and looping structures may be nested to about 15 
levels. When you are nesting conditionals, they must be 
properly paired, that is, an inner condition must begin and end 
completely within an outer condition. Here is an example of 
proper nesting and pairing: 


BEGIN, eee 
BEGIN, .e. 
WHILE, .-e. 

IF, eee 
ELSE, coe 
IF, eee 
THEN, «ee 
THEN, eee 
REPEAT, .- 
UNTIL, eee 
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At assembly time, there are checks for proper pairing of 
conditionals. Here are some improperly paired conditionals: 


BEGIN, .e- 
IF, eee 

UNTIL, 
THEN, 


Improper pairing will cause the error message "UNPAIRED 
CONDITIONAL” to be displayed and the assembly process will be 
terminated. 
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TABLE H.l SUMMARY OF ASSEMBLER WORDS 


ADDRESSING MODES: 


a 
7X 
r¥ 
) 
X) 
)Y 


OPCODES 


Immediate. 

Page zero and absolute, indexed by X-register. 
Page zero and absolute, indexed by Y-register. 
Absolute indirect. 

Page zero indexed by X indirect. 

Page zero indirect, indexed by Y. 

Page zero and absolute modes are defaults. 


Register transfer: 


LDA, 
STA, 


TSX, 
TXS, 


Arithmetic & logical 


LDX, LDY, 
STX, STY, 


TXA, TYA, 
TAX, TAY, 


ADC ’ AND ’ ASL ’ ROL ’ 

SBC, ORA, LSR, ROR, 
EOR, 

Comparison: 

CMP, CPX, CPY, 

Increment/decrement: 

INX, INY, INC, 

DEX, DEY, DEC, 

Stack 

PHA, PHP, 

PLA, PLP, 


Set/clear flags: 


CLC, 
SEC, 


CLD, Chl; CLV, 
SED, SEI, BIT, 
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TABLE H.1 


Flow of control: 


JSR, 
RTS, 


BNE, 
BEQ, 


BRK, IMP, 
RTI, 


BPL, BCC, 
BMI, BCS, 


( version 1 ) 


ELSE, 

UNTIL, 
Or 

ENDIF, 


BEGIN, BEGIN, 
WHILE, UNTIL, 
REPEAT, or 
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NOP, 


BVC, 
BVS, 


BEGIN, 
AGAIN, 


Additional assembler and assembler-related words: 
;CODE (;CODE) END-CODE 


CODE 
RA 
Ww 
BOT 
POP 


TABLE H.1 


RX RY 
IP N XSAVE 
SEC 
POPTWO PUSH PUT 
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Figure I.l1 is a memory map of the Apple II version of 
MicroMotion FORTH-79. The address locations given are in 
hexadecimal. 


The zero-page registers are used by the FORTH address 
interpreter and are described in appendix H.5. The N area is 
from 0001 to 0015 (N is at 0002). The IP is at 0016, Wis at 
0019, and XSAVE is at 001B. RA is at 001C, RX is at 001D, and 
RY is at OO1E (see appendix G.5). The parameter stack grows 
downwards from location OOFF to location 0050. 


The return stack shares the 6502 machine stack with the 
terminal input buffer. Both machine-language and FORTH word 
calls push return addresses on the machine stack without 
conflict. The machine stack grows downwards while the terminal 
input buffer grows upwards. The terminal input buffer will 
never exceed location 0164. 


The dictionary begins at location 0800 and grows upwards. 
The disk buffers end at location B600. Normally, four disk 
buffers are present and occupy the region from A5FO to B600. 
New buffers created with the word BUFFERS grow downwards toward 
the dictionary. The words BUFFERS and CREATE both test to see 
if there is sufficient room in memory before executing. 


With four disk buffers, about 20K of memory is left for 
dictionary growth. Programs which do not make use of 
high-resolution graphics may use the 8K memory bytes of the 
HIRES graphics page for additional data storage. Another 2K of 
memory can be saved by FORGETing the EDITOR before compiling the 
program, but this makes corrections rather difficult. Yet 
another 2K can be saved by FORGETing the ASSEMBLER if no CODE 
definitions are used within the application program. 


The extra 16K of memory on the Apple Language Card may be 
used if available. The FORTH program must select the 12K RAM 
area with the appropriate 4K memory bank and write-enable it. 
Since some FORTH words access the Apple monitor routines, care 
should be taken to select the language card ROM as soon as_ RAM 
access is complete. 


If additional storage is needed, the mass-storage device 


can be made to look like a large memory array by methods given 
in chapter 6, Mass Storage and the Editor. 
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MicroMotion FORTH provides disk utilities for buffer 
reallocation, block/screen backup, indexing and cataloging 
block/screen contents, and turnkey control. 


Jel BUFFER REALLOCATION 


The constant NBUF indicates how many disk buffers are 
currently allocated in your memory space: 


NBUF . 4 OK 


Four buffers (containing 1024 bytes each) are enough for normal 
programming. 


The constant MAXBUF indicates the maximum number of buffers 
which can be squeezed into memory: 


MAXBUF . 21 OK 
As your dictionary grows, MAXBUF will shrink accordingly. 


If your program needs to access many disk blocks/screens on 
a regular basis, you may wish to increase the number of 
buffers. For example, you may want to write a block sorting 
program or access a large data base. You can change the number 
of buffers with the command BUFFERS: 


10 BUFFERS OK 


BUFFERS automatically attempts a SAVE-BUFFERS followed by an 
EMPTY-BUFFERS to ensure that no previously altered blocks are 
lost. BUFFERS ensures that you have at least four buffers and 
no more than the MAXBUF number of buffers. You should return to 
using four buffers whenever possible to allow room for the 
dictionary to grow. 


2-2 MOVING AND BACKING UP BLOCKS 


The command LOAD-BUFFERS lets you move blocks into memory 
from mass storage, renumber them, and move them back out into 
mass storage. LOAD-BUFFERS requires the starting block number 
to move into memory, the new starting block number after 
renumbering, and the number of blocks to transfer: 


MOVING AND BACKING UP BLOCKS J.2 


DISK UTILITIES 186 


81 101 2 LOAD-BUFFERS OK 


Two blocks (81 and 82) are moved into memory and given the new 
numbers 101 and 102. All blocks moved into memory are updated 
(that is, marked as altered) by LOAD-BUFFERS. These blocks may 
now be rewritten to mass storage with the command SAVE-BUFFERS, 
replacing the previous contents of blocks 101 and 102. Since 
all the blocks read by LOAD-BUFFERS must be kept in memory until 
the SAVE-BUFFERS command, you can only read in as many blocks as 
you have buffers. If you try to read in more than this, 
LOAD-BUFFERS will stop you with an error message telling you how 
many blocks you can use. 


For example, if you wish to copy block 80 into block 100, 
type: 


80 100 1 LOAD-BUFFERS OK 
SAVE-BUFFERS OK 


LOAD-BUFFERS can also be used to move blocks from one disk 
to another. Simply change disks before typing SAVE-BUFFERS. 
This allows you to back up any part of a disk: 


MAXBUF BUFFERS OK 

50 50 20 LOAD-BUFFERS OK 
( Now change disks ) 
SAVE-BUFFERS OK 

( Change back again ) 

4 BUFFERS OK 


First, the sequence MAXBUF BUFFERS gives you as many buffers as 
possible. Assume that this is at least 20 buffers. Next, 50 50 
20 LOAD-BUFFERS loads blocks 50 through 69 into memory, without 
changing their numbers. Finally, changing disks and executing a 
SAVE-BUFFERS saves these blocks onto the new disk. Always 
remember to set BUFFERS to a reasonable number (such as_ four) 
whenever possible. LOAD-BUFFERS has been designed to move any 
block, including block zero. 


To back up an entire source text disk, use the utilities 
COPY-DISK or COPY-BLOCKS. See appendix C. 


Note: The easiest way to back up a dictionary is to boot up on 
that dictionary, change disks, and SAVE the dictionary. 
J.3 INDEXING AND CATALOGING 


The command INDEX lets you examine a range of screens on a 
disk: 


73 75 INDEX 
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INDEX simply prints the first line of each screen in the 
specified range. For this reason, the first line of every 
screen should be a comment. 


You will find the definition of the command CATALOG on the 
grandfather disk (see appendix A): CATALOG, like INDEX, also 
examines a range of screens, but in more detail: 


73 75 CATALOG 
273 1: CATALOG ( 1ST LINE OF DEFINITIONS) 
2 : DUMP ( START-ADDR #-BYTES --- ) 


REGIE 
™ 
E 
E 


Notice that only the first line of a definition is printed. 
Constant and variable definitions and other important 
information can also be selected with CATALOG. How does it 
work? CATALOG simply prints every line in the range of screens 
which does not begin with a blank. By proper indentation, you 
can specify which lines will be printed by CATALOG. As a matter 
of style, you should begin the first line of a screen (the 
comment line) with a blank. 


If you encounter an error while LOADing a program, use the 
command WHERE. This command activates the editor and positions 
you within the screen where the error was detected. 


Another MicroMotion disk utility, DOC, is used to list 
screens. poc lists 3 screens and the emits a _ form-feed 
character every page. On most printers, you can use DOC to 
format and print 3 screens on a 8 1/2 x ll-inch sheet of paper. 
For example, 73 76 DOC lists screens 73, 74, 75 and 76. 


J.4 TURNKEY AND PROTECTED DICTIONARIES 


Whenever you SAVE a dictionary, the system variable FENCE 
is updated to point to the last word in the dictionary. If you 
try to FORGET this word, or any preceding word, you will get a 
"protected dictionary" error message. The SAVEd dictionary is 
protected. Any words you add to it are unprotected until you 
SAVE again. For example, to protect all words preceding and 
including the word TASK, type: 


' TASK FENCE ! OK 
To remove the protection completely, type: 
0 FENCE ! OK 
When you boot up from a FORTH disk, control is normally 
given to the FORTH interpreter. If you have developed an 
application program, you may want this program to run 


immediately. The command TURNKEY lets you effectively 
substitute your program for the FORTH interpreter: 
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TURNKEY MAIN-PROGRAM OK 


If you now SAVE this dictionary, the word MAIN-PROGRAM will run 
when the disk boots up. Your application program must begin 
with EMPTY-BUFFERS and can return control to the FORTH 
interpreter at any time with: 


' GO CFA (BOOT) ! WARM 


Warmstarts and certain errors will normally return control 
to the FORTH interpreter. You can change this with the command 
ONERR: 


ONERR CATCH-ERRORS OK 


Any subsequent warmstart or error will now execute the word 
CATCH-ERRORS. ONERR may only be executed directly and it is 
effective immediately. ONERR is still effective after a disk is 
booted up, if the dictionary was SAVEd after an ONERR command. 
You can cancel ONERR with: 


' QUIT CFA (ABORT) ! 


Be careful not to save a TURNKEY dictionary on your working 
FORTH disk. If the TURNKEY word does not have a provision for 
returning to the FORTH interpreter, you will effectively lose 
the use of the FORTH dictionary on that disk. 


If you plan to use your application program for commercial 
purposes, you must take the following actions: 


1. You must disable the FORTH language dictionary with 
the word DESTRUCT: 


DESTRUCT OK 
DESTRUCT destroys the compile-time code of the 
flow of control instructions. Words which are already 
compiled will run properly, but new words cannot be 
added to the dictionary. 


2. You must include a prominent notice on your product 
package: 


Written in MicroMotion FORTH-79 


This notice must also appear on the title page of 
your instruction manual. 


3. You must notify us of your intentions by sending us a 
product description or product release. Send to: 


MicroMotion 


12077 Wilshire Blvd, Suite 506 
Los Angeles, CA 90025 
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This appendix describes the internal structure of the 
MicroMotion FORTH-79 and FIG-FORTH dictionary. Each word in the 
dictionary has four fields: the name field (NF), the link field 
(LF), the code field (CF), and the parameter field (PF). The 
FORTH-79 International Standard allows access only to the 
parameter field. This ensures that FORTH-79 programs will be 
independent of the internal dictionary structure. 


Here is a diagram of the dictionary structure: 


---------- <---- lst word in dictionary 
! NF sname !<-- 


= 
a2) 
ry 
ee 
Qu 
is} 
cr 
» 
— 
— oe oe Ge Oe ee Oe ee ee Oe fe 


! | ---------— ! 

! $0F 3 x*x-<——--- 
! | -<-------- ! 

! ! CF :code ! 

! | ---------- ! 

! ! PF :data ! 

| 

! 

| Cee 

! ! NF sname !<---- LATEST word added to dictionary 
!  Jeee------- ! 
------- x:LF  ! 


---------- <---- end of dictionary 


The address of the parameter field (the PFA) of any word can be 
found with the word ' ("tick"). The name field address (NFA), 
link field address (LFA) and code field address (CFA) can be 
found from the PFA with the words NFA, LFA, and CFA, 
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respectively. For example, to find the CFA of the word XYZ, 
type: 


' XYZ CFA 


The address of the code field of XYZ will be left on the’ stack. 
The PFA can also be found from the NFA with the word PFA. 


The name field (NF) is simply a character string whose 
value is the name of the word. The first byte of the string is 
the “natural length" of the word. The natural length of a word 
is the number of characters in the name originally given to the 
word. The number of characters actually stored in the NF is 
limited by the system variable WIDTH. The value of WIDTH should 
range between 2 and 31 (decimal). For example, if WIDTH is four 
and the word TEMPERATURE is defined, the natural length (11) 
followed by the character string TEMP will be stored in the NF. 
The name of a word can be printed from the NFA with the command 
ID.: 


* ABC NFA ID. ABC OK 


It is possible for two words with different names to have 
the same NF. For example, if WIDTH is four, FINISH and FINITE 
will have identical NFAs but FINISH and FINISHED will not (since 
their natural lengths are unequal). If two words have identical 
NFs, FORTH will treat them as multiple definitions of the same 
word. In multiple definitions, FORTH always uses the word most 
recently defined. 


The NF is delimited by setting the high-order bit (bit 7) 
of both the first (the natural length) and last (the final 
character) bytes. For example, the NF of the word ABC is (in 
hex): 83 41 42 C3. 


Bits 5 and 6 in the first byte of the NF have special 
meanings. If bit 6 is set, the word is an IMMEDIATE word. The 
NF of the IMMEDIATE word ABC is C3 41 42 C3. Bit 5 is set while 
a word is being defined and reset when the definition is 
complete. This is called "smudging" the NF. Recursive 
definitions are not allowed in FORTH, and smudging a_ word 
prevents the definition in progress from finding itself in the 
dictionary. However, earlier definitions may still be found. 


The link field (LF) chains the words in the dictionary 
together. The LF contains a pointer to the NF of the preceding 
word. The system variable LATEST contains a pointer to the NF 
of the most recently defined word in the dictionary (depending 
on the CONTEXT). The LF of the first word in the dictionary is 
zero. 
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The following FORTH sequence illustrates how to traverse 
the dictionary: 


LATEST ( NFA OF MOST RECENT WORD ) 
BEGIN ( NFA OF EACH WORD ) 

( «e+ ANY CODE ) 

PFA LFA @ ( NFA OF NEXT WORD ) 

DUP 0= 
UNTIL DROP 


The code field (CF) always contains a pointer to machine 
code. This is required by the indirect threaded code algorithm 
used by the inner interpreter. The CF usually points to DOCOL, 
which redirects FORTH flow of control to the following parameter 
field. The CF of words defined by CODE or ;CODE simply points 
directly to the following parameter field. The CF may also 
point to DOVAR (variables), DOCON (constants), or special 
machine-code subroutines (CREATE ... DOES> compiler words). 


The parameter field (PF) contains the data or code used by 
the FORTH word. The PF of a variable, constant or array holds 
data. The PF of a FORTH word defined with a colon holds the CFs 
of each word used within the definition, ending with the ; 
("semicolon") CF. IMMEDIATE words used within a definition do 
not always add a CF to the PF of the word being defined. The PF 
of a CODE or ;CODE word contains the actual machine code of the 
word. The PF of compiler words using CREATE...DOES> may contain 
complex combinations of data and code. 
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MESSAGE EXPLANATION 


EMPTY STACK 


DICTIONARY 
FULL 


BAD ARGUMENT 


NOT UNIQUE 


TOO BIG 


DISK RANGE 


FULL STACK 
DISK ERROR 
COMP. ONLY 


EXEC ONLY 


CONDITIONAL? 


UNFINISHED 


PROTECTED 


NOT FORTH79 


DELIMITER? 


An argument cannot be pulled from an empty 
Parameter stack. 


There is insufficient memory for the 
dictionary to grow. 


(ASSEMBLER) An illegal machine-code 
address mode has been requested. 

The word displayed has been called with 

an invalid argument. 

NOTE: This is a warning, not an error. 

The word being defined has been previously 
defined. 


(ASSEMBLER) A relative branch instruction 
cannot branch to an out-of-range label. 


The BLOCK number requested is larger than 
the largest BLOCK available on the disk. 


The parameter stack is full. 
FORTH is unable to read/write the disk. 


The word displayed can only be used 
during compilation. 


The word displayed cannot be used 
during compilation. 


A flow-of-control construct has been 
incorrectly terminated or nested. 


The definition of the word displayed was 
finished before all flow-of-control 
constructs were terminated. 


An attempt has been made to FORGET a word 
in a protected dictionary. 
See appendix J, Disk Utilities. 


The word displayed is not portable. 

(See appendix M. ) 

The input stream was exhausted before an 
ending delimiter was found. 
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A program can be called portable if it will run ona 
variety of computers with little or no modification. Portable 
software cannot take advantage of the special hardware features 
of a particular computer. Nevertheless, there are important 
reasons for writing portable code. Portable programs can be 
written once and then sold for use on _ several computers. 
Portable programs are also more likely to survive the transition 
from an obsolete computer to its replacment. 


One way to make a =e program portable is to write it in a 
Standardized language. A program written in standard FORTRAN or 
COBOL, for example, will probably run unchanged on most large 
computers. UCSD PASCAL is an example of a microprocessor-based 
language which has achieved relatively high portability through 
standardization. 


All portability schemes, however, must deal with two major 
problems: the apparently inescapable link between the speed of a 
language and its machine dependence, and the difficulty of 
standardizing input/output (I/O) interfaces. These are the 
reasons why no truly universal language has appeared and why 
serious programmers often end up writing in assembly language. 


In the search for a good portable language, FORTH has 
emerged as one of the most promising. It is extremely fast and 
compact in comparison with most high-level languages; in fact, 
it can be even more compact than machine code. Another of 
FORTH's attractive features is its structured form--the way in 
which it allows the specification of complex tasks by invoking 
previously-defined words. Typically, a FORTH program requires a 
small set of Drimitives--words which must be written in machine 
code to get the language "off git steunas” so to speak. The 
remainder of the language, and the program itself, are written 
in FORTH. All that it takes for a program written on one machine 
to run on any other (ignoring I/O considerations for the moment) 
is to rewrite the small set of primitives in the machine code of 
the target computer. 


FORTH's greatest advantage over any other language, though, 
lies in its built-in knowledge of the operating system 
"environment." For an example of what this means, let's compare 
how disk files are accessed in FORTRAN and in FORTH. FORTRAN has 
no specified way of writing information to a disk; if you have 
written a FORTRAN program using disk storage on one computer, 
you will have to study the operating system of any new computer 
to learn how to interface your program to its disk. FORTH, on 
the other hand, uses the word BLOCK to specify exactly how 
information is read from and written to the disk. Furthermore, 
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the words KEY and EMIT specify the interface to the user, who is 
assumed to be typing on the "standard input keyboard" and 
reading from the "standard output device." 


The FORTH-79 Standard, published in October 1980, further 
strengthens the portability of FORTH programs by specifying a 
minimum word set which must run identically on all FORTH-79 
language implementations (see appendix D). The Standard also 
restricts programming practices which would destroy 
portability. 


MicroMotion FORTH-79 version 2 meets the FORTH-79 Standard. 
In addition, MicroMotion FORTH includes some built-in features 
(described below) to make it easy to write portable programs. In 
the following sections, we will use the term standard for words 
which are listed in the FORTH-79 Standard, or whose definitions 
are based solely on words listed in the Standard. Non-standard 
words are those which are not primitives, and whose definitions 
use terms not derived from the Standard and are therefore not 
portable. 


M.l THE IMPROVED YLIST 


MicroMotion FORTH-79's normal VLIST command lists only the 
names of the words in the dictionary: 


VLIST 
SETPLASH 
SETINV 
SETNORM 
PBUTTON 
PADDLE 


(hit any key to stop) 


A more sophisticated VLIST is provided on screens 76 and 77 of 
the grandfather disk: 


76 77 THRU 
OK 
VLIST NOT UNIOUE OK 


2 SCAF (FD6) VLIST 

4 5C8B (FD6) INFO 

6 SBDE (E43) (INFO) 

6 SBB3 (AA4) (ADDR) 

8 SB9C (80E) (SETFLASH) 
6 5B87 (80E) SETINV 


(hit any key to stop) 


Dictionary entries preceded by N are non-standard and 
non-portable. Entries lacking the N are standard, but this is 
not in itself a guarantee that they are portable, for some words 
that are not normally primitives have been given CODE 
definitions for the sake of speed. We will explain this rather 
confusing distinction and learn how to get around it, in the 
sections below. For a detailed description of VLIST, see 


THE IMPROVED VLIST M.1 
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appendix C (Glossary). 


The MicroMotion FORTH-79 compiler uses a simple algorithm 
to determine whether words are portable. If any word in a colon 
definition is non-standard, the definition itself becomes 
non-standard. Furthermore, CODE words are always declared 
non-standard. A program written to meet the FORTH-79 Standard 
must contain only standard words. 


M.2 SPEED VERSUS PORTABILITY 
Consider a standard definition of the word 2*: 
: 2* 2* ; 


Defined this way, 2* will run on any machine which supports the 
FORTH-79 Standard. Another way to implement 2* is to write it in 
machine code, taking advantage of an arithmetic-shift-left 
operation. This CODE definition of 2* runs hundreds of times 
faster than the colon definition above, but it is not portable. 
It would be useful to have a screen with both definitions side 
by side and to be able to select one or the other depending on 
whether you want your program to be portable or fast. 


MicroMotion FORTH-79 features portable brackets which allow 
you to do just this. A standard definition of 2* takes the form 


)) 


A non-standard, optimized definition might be 


CC «2* 2 


(& CODE 2* ( 6502 Version ) 
BOT ASL, BOT 1+ ROL, 
NEXT JMP, END-CODE &) 


These new symbols-- (( (& )) and &) --are in fact FORTH 
words which affect the input stream to the compiler. 


The variable MODE selects which type of portable brackets 
the compiler will "see" and which it will "ignore" when 
compiling a screen. If the value of MODE is zero, you are in 
79-Standard mode. If the value is 1, you are in optimizer mode. 
To set MODE, simply type 79-STANDARD or OPTIMIZER, 
respectively. 


Now say you are in 79 Standard mode and you LOAD a screen 
containing the two definitions of 2* given above. The compiler 


will see the portable brackets-- (( )) --as a go-ahead to 
compile the colon definition inside them, and will do so. At the 
same time, anything within the optimizer brackets-- (& &) 


--will be treated as a comment, so the CODE definition will be 
skipped. If you type OPTIMIZER before LOADing the screen, the 
CODE definition between (& and &) will be compiled, while 
the colon definition within the standard brackets-- ( ( )) 
--will be skipped. In the latter case the VLIST will now’ show 
that 2*, as you have just defined it, is a non-standard word. Of 
course, definitions lacking either type of brackets will not be 
subjected to this "screening" and will be compiled regardless, 
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as they have been all along. 


The MicroMotion FORTH-79 dictionary comes with the CODE 
(non-standard) definition of 2*. Suppose you return to 79 
Standard mode and attempt to define a word which uses this 
non-standard 2*: 


79-STANDARD OK 
: 3* DUP 2% # 3 
3* NOT STANDARD OK 


FORTF warns you that the word 3* is non-standard. This is only a 
warning; you may ignore it if you wish, and 3* has been compiled 
anyway. In optimizer mode, no such warnings are issued. 


M.3 TESTING PORTABILITY 


The word OPTIMIZER in your dictionary forms a dividing 
line; all words below it are either members of the 79 Standard 
(whether they are colon or CODE definitions) or else they are, 
like 2*, capable of being defined in Standard terms. To test a 
program for portability, you must first FORGET all words from 
OPTIMIZER up: 


0 FENCE ! FORGET OPTIMIZER OK 


Next, you may want to LOAD the standard definitions for the 
remaining non-standard words (like 2*) from the grandfather 
disk, screens 95 through 99: 


( Insert grandfather disk ) 


( EMPTY-BUFFERS if necessary) 
95-99 THRU eeee OK 


Finally, set 79-STANDARD mode and LOAD your program screens: 


( Insert program disk ) 

EMPTY-BUFFERS 79-STANDARD OK 

( Assume program is on screens 15 through 29 ) 
15. 29 THRU sec OX 


Most non-standard words in your program will generate warning 
messages as they are compiled. However, there are a few further 
requirements for portability which cannot be easily checked by 
the compiler. First, a Standard program may NOT address: 


1. directly into the data or return stacks, 

2. into a definition's name field, link field, or code 
field, or 

3. into the definition's parameter field if the latter has 
not been stored earlier by the program. 


Each of these practices would make direct reference to the 
hardware structure of a specific machine. 
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Standard programs must be accompanied by statement 
specifying the minimum requirements for the target machine suc 
as: 


1. System dictionary space. This can be determined by th 
sequence: 


HEX 0 FENCE ! FORGET OPTIMIZER HERE 800 - DECIMAL U. 
2. Application dictionary space. Type 
HEX HERE 800 - DECIMAL U. 


after compiling your program, and subtract the syste 
dictionary space from the result. 


3. Data stack. 64 bytes, unless you need more. 
4. Return stack. 48 bytes, unless you need more. 


5. Number of contiguous blocks of mass storage. 32 blocks 
numbered 0 through 31, unless you need more. 


6. Operator's terminal. This should be an ASCI 
input/output device capable of accepting and displayin 
all characters required by FORTH. The display shoul: 
have direct or scroll display of at least 16 lines of 6 
characters. A backspace or delete key is als: 
necessary. 


Finally, you must provide a statement of the system's actio! 
upon each of the error conditions as identified in the FORTH-7:! 
Standard. You may copy these from appendix L, Error Messages. 


M.4 THE INPUT/OUTPUT VECTOR 


The MicroMotion FORTH-79 language communicates with thi 
host computer operating system through four words: KEY, EMIT 
?KEY, and BLOCK (via R/W; see appendix C, Glossary). Each o: 
these words transfers control to an address stored in thi 
parameter-field of IOVEC, which is defined thus: 


VARIABLE IOVEC -2 ALLOT 

' (KEY) , ( machine code for KEY ) 

' (EMIT) , ( machine code for EMIT ) 
' (?KEY) , ( machine code for ?KEY ) 
FIND (R/W) , ( FORTH code for R/W ) 


The first three addresses-- (KEY), (EMIT), and (?KEY) --musi 
refer to the parameter-field address (PFA) of CODE words endin 
with a return-from-subroutine instruction. The fourth address-- 
(R/W) --is simply the code-field address (CFA) of a COD! 
definition ending with a jump instruction to NEXT or a colo! 
definition. 


You may replace any of these input/output words with you) 


own custom function by storing the appropriate address in IOVEC, 
For example, if you have written an input subroutine calle 
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YKEY which allows the user to enter special keys not available 
rom the keyboard, you can install this subroutine in the 
anguage by typing: 

' MYKEY IOVEC ! OK 


ny use of KEY will now call MYKEY. The normal KEY function can 
e restored by typing: 


" (KEY) IOVEC ! OK 
uppose you have added a hard disk to your system and have 
‘ritten a variation of R/W called R/WD to access it. BLOCK will 
se R/WD instead of R/W if you type: 

FIND R/WD IOVEC 6 + ! OK 


‘emember, R/WD must be a normal FORTH colon definition. 
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